Setting up webhooks

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.

Try it in the console→

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.
2. Send a test.ping before relying on production alerts — Testing and troubleshooting.
3. Review the event catalog so you subscribe only to what you handle.