Set up webhooks

Webhooks send an HTTPS POST to your service when subscribed events occur in Kato. Use them to trigger work or keep another system up to date.

Create an endpoint

In Settings → Workspace → Developers, open the Webhooks section. Register your receiver URL, select the events you need, and save the signing secret shown at creation.

For API-driven setup, create an access key with webhooks:write and send:

curl --fail-with-body --silent --show-error \
  https://api.getkato.io/v1/webhooks \
  -H "Authorization: Bearer $KATO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "target_url": "https://your-service.example/webhooks/kato",
    "description": "Sync client records",
    "events": ["record.created", "record.updated", "record.deleted"]
  }'

Replace the example URL with your deployed receiver. The target must use HTTPS and resolve to a public address. Localhost, private networks, URL credentials, and redirects are not supported. For local development, use a public HTTPS tunnel to your local receiver.

The response is 201 with data.id, data.targetUrl, data.description, data.events, data.status, data.createdAt, data.updatedAt, and data.secret. Save the complete whsec_… signing secret in your receiver's secret store. Listing endpoints will not return it again.

Verify before processing

Every delivery includes an X-Kato-Signature header. Verify it against the original request bytes before parsing or acting on the JSON.

Follow Verify and process webhooks for a Node.js verifier, replay protection, and duplicate handling. The signing secret is different from your kato_… API access key.

Management endpoints

Paths are relative to https://api.getkato.io/v1.

Creation accepts target_url (up to 2,048 characters), optional description (up to 200 characters or null), and a nonempty events array.

The public API currently has no endpoint-update, replay, or secret-rotation route. Use the Webhooks UI to inspect delivery logs, replay a delivery, and enable an endpoint that has been disabled.

If you lose a secret or need a different URL or event subscription, create a replacement endpoint, configure its secret, verify delivery, then delete the old endpoint. Handle duplicates while both subscriptions are active.

Delivery behavior

Return a 2xx response after the event has been safely accepted. Requests time out after 10 seconds, so queue slower work and acknowledge promptly. Non-2xx responses, network errors, and timeouts cause delivery failures and automatic retries with backoff. Redirects are not followed.

Events may arrive more than once or out of order. Deduplicate by the signed payload's id, using persistent storage. Automatic retries may reuse a delivery ID; manual replay creates a new delivery ID while preserving the event ID and payload.

An endpoint is disabled after 15 consecutive failed events; a successful delivery resets the failure count. Only the first failure of a delivery increments this counter; automatic retries do not increment it again. Inspect the logs, fix the receiver, enable the endpoint, and replay the deliveries you need.

Test a subscription

1. Configure your receiver and signing secret.
2. Create or update a test record in the subscribed workspace.
3. Inspect its delivery in the Webhooks logs.
4. Confirm signature verification succeeds and your queued work runs.
5. Replay the same event and confirm it does not apply the change twice.

New subscriptions do not replay historical events, and newly added event types are not automatically included in an existing subscription. Use the event reference and GET /webhooks/events to select explicit event names.