---
title: "Setting up webhooks"
description: ""
canonical: "https://kingminos.com/docs/webhooks/setup/"
sourceKind: "source-mdx"
---

import TryItLink from '../../../../components/docs/TryItLink.astro';

## Prerequisites

1. A KingMinos account with a workspace (`https://app.kingminos.com`).
2. **Webhooks enabled on the workspace** — ask an OutboundSync admin. Without it, `/v1/webhooks*` and `/v1/events` return `403 webhooks_not_enabled`.
3. A workspace-bound credential: a signed-in session, or a personal `km_` token. **Mutations (create, update, delete, rotate, test, replay) need the workspace owner.**

## Register an endpoint

You can register through the API (the app UI follows). Webhook calls need an API token that carries the **`webhooks` scope**: in the app, go to API tokens → Create token and check **Can manage webhooks** (API: `scopes: ["capability:*", "webhooks"]`). Default tokens don't include it, so an integration key can't change your webhooks unless you grant it. Without the scope, every webhook route returns `403 webhook_scope_required`.


1. `POST /v1/webhooks` with your HTTPS `url`, optional `description`, and optional `enabled_events`.
2. Store the returned `secret` (`kmwhsec_…`) — **it is shown once and never again**.
3. `POST /v1/webhooks/{id}/test` and confirm the delivery `succeeded`.

<TryItLink method="POST" path="/v1/webhooks" />

```bash
KINGMINOS_API_KEY=…  # owner key with the webhooks scope
curl -sS https://api.kingminos.com/v1/webhooks \
  -H "Authorization: Bearer $KINGMINOS_API_KEY" \
  -H "content-type: application/json" \
  -d '{"url":"https://hooks.example.com/kingminos","enabled_events":["run.failed","run.recovered"]}'
```

## URL rules and limits

- **HTTPS only.** Private, loopback, and link-local targets are rejected — including hostnames that resolve to those ranges over DNS. The check runs at create and again on every delivery attempt.
- **Redirects are not followed.** Register the final URL; a `3xx` response counts as a failed attempt.
- An empty (or omitted) `enabled_events` receives all **active** event types. Reserved names return `400 invalid_webhook_events` with the available list.
- A workspace may register at most **20** endpoints.
- `DELETE /v1/webhooks/{id}` soft-deletes an endpoint.

## Next steps

1. Verify signatures on your endpoint — [Payloads and signatures](/docs/webhooks/payloads-and-signatures/).
2. Send a `test.ping` before relying on production alerts — [Testing and troubleshooting](/docs/webhooks/testing-and-troubleshooting/).
3. Review the [event catalog](/docs/webhooks/event-types/) so you subscribe only to what you handle.