Webhooks
Create a webhook endpoint
Register a public HTTPS destination for selected delivery events.
POST
/api/v1/webhooksOn this page
Authentication
Send a RouteKite API key as a Bearer token. This endpoint requires the webhook:manage scope.
| Name | Type | Requirement | Description |
|---|---|---|---|
Authorization | string | Required | Bearer API key with the required workspace scope.Example: Bearer rk_your_key |
Request body
| Name | Type | Requirement | Description |
|---|---|---|---|
url | https URL | Required | A public HTTPS endpoint on port 443. |
description | string | Optional | A short label, up to 160 characters. |
events | event[] | Required | One or more unique email delivery event names. |
Response
| Name | Type | Requirement | Description |
|---|---|---|---|
object | string | Always | Always webhook_endpoint. |
id | uuid | Always | Endpoint ID. |
url | url | Always | The validated public HTTPS URL. |
description | string | Always | The endpoint label, or an empty string. |
event_types | event[] | Always | The subscribed normalized delivery events. |
state | string | Always | The endpoint state. |
created_at | date-time | Always | When the endpoint was created. |
signing_secret | string | Creation only | Secret used to verify signed requests. Present for default API creation only; omitted with secret_delivery=dashboard. |
setup_url | https URL | Dashboard handoff only | Authenticated setup page for the creating member. The URL contains no signing secret. |
setup_secret_expires_at | date-time | Dashboard handoff only | End of the one-time reveal window, 24 hours after creation. |
Signing secret
The creation response includes the endpoint signing secret. Store it only in your server environment and use it to verify every request.
AI clients use the optional secret_delivery=dashboard query parameter instead. That response contains a setup_url, not signing_secret. The creating member opens the link in RouteKite, verifies their password, and saves the secret once within 24 hours. Existing webhooks and default API creation remain unchanged.
Workspace capacity
A workspace can keep up to 10 active webhook endpoints. Delete an unused endpoint before creating another after the limit is reached.
Errors
| Status | Code | What it means | What to do |
|---|---|---|---|
| 400 | INVALID_REQUEST | The endpoint input or identifier is invalid. | Correct the reported field. |
| 401 | UNAUTHORIZED | The API key is invalid. | Check the Bearer header. |
| 403 | FORBIDDEN | The key lacks webhook:manage access. | Use a key with the required scope. |
| 404 | WEBHOOK_NOT_FOUND | The endpoint is unavailable in this workspace. | Check the endpoint ID and workspace. |
| 409 | WEBHOOK_ALREADY_EXISTS | The destination is already registered. | Use the existing endpoint or delete it first. |
| 409 | WEBHOOK_ENDPOINT_LIMIT_REACHED | The workspace already has 10 active webhook endpoints. | Delete an unused endpoint before creating another. |
| 422 | INVALID_WEBHOOK_URL | The destination is not a public HTTPS endpoint. | Use a public HTTPS URL on port 443. |
| 503 | WEBHOOK_DESTINATION_UNAVAILABLE | The destination could not be resolved because of a transient DNS failure. | Retry the same request after a short delay. |
| 429 | RATE_LIMITED | Too many requests were sent in a short period. | Honor Retry-After before retrying. |
| 500 / 503 | INTERNAL_ERROR | The operation could not complete. | Retry after a short delay. |