API ReferenceWebhooks

Webhooks

Manage workspace webhook subscriptions and receive signed incident events.

Search API docsAll documentation

Search all guides and API reference text. Method and scope filter endpoints only.

MethodScope

Endpoints

List webhook subscriptions

GET/api/v1/settings/webhooks

Lists the webhook subscriptions in the workspace. The response shows the HTTPS scheme and host of each destination. It does not show a signing secret.

This API is in preview. Tellagen can change the webhook event contract before this API becomes supported.

Required scope: webhooks:manage
Also required: Manage workspace settings

Example request

Replace {company}, <token>, and any other placeholders with your values.

bash

curl --request GET \
  --url 'https://{company}.api.tellagen.com/api/v1/settings/webhooks' \
  --header 'Authorization: Bearer <token>'

Success: 200

Returns all webhook subscriptions in the workspace.

Success response JSON

json

{
  "webhooks": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "url": "https://hooks.example.test",
      "event_types": [
        "incident.created"
      ],
      "status": "active",
      "created_at": "2026-09-14T10:00:00Z",
      "updated_at": "2026-09-14T10:00:00Z",
      "last_success_at": null,
      "last_failure_at": null
    }
  ]
}

Parameters, headers, and fields

Operation ID: listWebhookSubscriptions

Response `200`

Returns all webhook subscriptions in the workspace.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`webhooks` object[] Always returned	The webhook subscriptions in the workspace.
`webhooks[].id` string Always returned	The webhook subscription ID.
`webhooks[].name` string Sometimes returned	An optional display name for the webhook subscription. Maximum length: 100 characters.
`webhooks[].url` string Always returned	The HTTPS scheme and host of the destination. Responses omit the path and query string.
`webhooks[].event_types` string[] Always returned	The event types that the subscription receives. Minimum items: 1. · Items must be unique. Possible values: `"incident.created"`
`webhooks[].status` string Always returned	The delivery state of the subscription. Possible values: `"active""paused""revoked"`
`webhooks[].created_at` string (RFC 3339) Always returned	The time when the subscription was created.
`webhooks[].updated_at` string (RFC 3339) Always returned	The time when the subscription last changed.
`webhooks[].verified_at` string (RFC 3339) Sometimes returned	The time of the receiver check. Absent until verified. Active subscriptions require this value.
`webhooks[].last_success_at` string (RFC 3339) \| null Always returned	The time of the most recent successful delivery. The value is null before a successful delivery.
`webhooks[].last_failure_at` string (RFC 3339) \| null Always returned	The time of the most recent failed delivery. The value is null before a failed delivery.

Errors and recovery (7)

You can repeat this request. If the API returns 429, wait for Retry-After. Set a maximum number of attempts. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Create a webhook subscription

POST/api/v1/settings/webhooks

Creates a paused webhook subscription. Use a public HTTPS URL on port 443. Save the one-time signing secret in the receiver, then verify it to start delivery.

If event_types is omitted, the API sends incident.created events. This API is in preview. Tellagen can change the webhook event contract before this API becomes supported.

Required scope: webhooks:manage
Also required: Manage workspace settings

Example request

Replace {company}, <token>, and any other placeholders with your values.

bash

curl --request POST \
  --url 'https://{company}.api.tellagen.com/api/v1/settings/webhooks' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://hooks.example.test/tellagen",
  "event_types": [
    "incident.created"
  ]
}'

Success: 201

Returns the created subscription and its signing secret. The secret appears only in this response.

Success response JSON

json

{
  "webhook": {
    "id": "22222222-2222-4222-8222-222222222222",
    "url": "https://hooks.example.test",
    "event_types": [
      "incident.created"
    ],
    "status": "paused",
    "created_at": "2026-09-14T10:00:00Z",
    "updated_at": "2026-09-14T10:00:00Z",
    "last_success_at": null,
    "last_failure_at": null
  },
  "secret": "whsec_example_secret_value"
}

Parameters, headers, and fields

Operation ID: createWebhookSubscription

Request body

Optional fields can be omitted. To clear a value, use the format in its description. Nested fields apply only within their parent object.

Request body fields
Field	Description
`name` string Optional	An optional display name. Leading and trailing whitespace is removed. Maximum length: 100 characters.
`url` string Required	An absolute HTTPS URL that resolves to a public address. Maximum length: 2048 characters.
`event_types` string[] Optional	The event types to send. If omitted, the API sends incident.created. Minimum items: 1. · Items must be unique. Allowed values: `"incident.created"`

Response `201`

Returns the created subscription and its signing secret. The secret appears only in this response.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`webhook` object Always returned	A workspace webhook subscription.
`webhook.id` string Always returned	The webhook subscription ID.
`webhook.name` string Sometimes returned	An optional display name for the webhook subscription. Maximum length: 100 characters.
`webhook.url` string Always returned	The HTTPS scheme and host of the destination. Responses omit the path and query string.
`webhook.event_types` string[] Always returned	The event types that the subscription receives. Minimum items: 1. · Items must be unique. Possible values: `"incident.created"`
`webhook.status` string Always returned	The delivery state of the subscription. Possible values: `"active""paused""revoked"`
`webhook.created_at` string (RFC 3339) Always returned	The time when the subscription was created.
`webhook.updated_at` string (RFC 3339) Always returned	The time when the subscription last changed.
`webhook.verified_at` string (RFC 3339) Sometimes returned	The time of the receiver check. Absent until verified. Active subscriptions require this value.
`webhook.last_success_at` string (RFC 3339) \| null Always returned	The time of the most recent successful delivery. The value is null before a successful delivery.
`webhook.last_failure_at` string (RFC 3339) \| null Always returned	The time of the most recent failed delivery. The value is null before a failed delivery.
`secret` string Sometimes returned	The signing secret. The API returns this field only after create or secret rotation.

Errors and recovery (7)

If the result is unknown, read the resource before another attempt. The error details explain the next step. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Verify a webhook receiver

POST/api/v1/settings/webhooks/{id}/verify

Checks that the receiver holds its signing secret, then activates delivery. The receiver must return the OPTIONS proof described in the webhook guide. Checks have a one-minute cooldown and shared request limits. Failed checks leave delivery paused.

Required scope: webhooks:manage
Also required: Manage workspace settings

Example request

Replace {company}, <token>, and any other placeholders with your values.

bash

curl --request POST \
  --url 'https://{company}.api.tellagen.com/api/v1/settings/webhooks/{id}/verify' \
  --header 'Authorization: Bearer <token>'

Success: 200

Returns the verified, active subscription.

Success response JSON

json

{
  "webhook": {
    "id": "22222222-2222-4222-8222-222222222222",
    "url": "https://hooks.example.test",
    "event_types": [
      "incident.created"
    ],
    "status": "active",
    "created_at": "2026-09-14T10:00:00Z",
    "updated_at": "2026-09-14T10:05:00Z",
    "verified_at": "2026-09-14T10:05:00Z",
    "last_success_at": null,
    "last_failure_at": null
  }
}

Parameters, headers, and fields

Operation ID: verifyWebhookSubscription

Path parameters

Path parameters
Field	Description
`id` string Required	A webhook subscription ID returned by this API.

Response `200`

Returns the verified, active subscription.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`webhook` object Always returned	A workspace webhook subscription.
`webhook.id` string Always returned	The webhook subscription ID.
`webhook.name` string Sometimes returned	An optional display name for the webhook subscription. Maximum length: 100 characters.
`webhook.url` string Always returned	The HTTPS scheme and host of the destination. Responses omit the path and query string.
`webhook.event_types` string[] Always returned	The event types that the subscription receives. Minimum items: 1. · Items must be unique. Possible values: `"incident.created"`
`webhook.status` string Always returned	The delivery state of the subscription. Possible values: `"active""paused""revoked"`
`webhook.created_at` string (RFC 3339) Always returned	The time when the subscription was created.
`webhook.updated_at` string (RFC 3339) Always returned	The time when the subscription last changed.
`webhook.verified_at` string (RFC 3339) Sometimes returned	The time of the receiver check. Absent until verified. Active subscriptions require this value.
`webhook.last_success_at` string (RFC 3339) \| null Always returned	The time of the most recent successful delivery. The value is null before a successful delivery.
`webhook.last_failure_at` string (RFC 3339) \| null Always returned	The time of the most recent failed delivery. The value is null before a failed delivery.
`secret` string Sometimes returned	The signing secret. The API returns this field only after create or secret rotation.

Errors and recovery (7)

If the result is unknown, read the resource before another attempt. The error details explain the next step. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Pause a webhook subscription

POST/api/v1/settings/webhooks/{id}/pause

Stops new deliveries for the subscription. Existing delivery records remain available for the worker and the subscription stays available for later resume.

Required scope: webhooks:manage
Also required: Manage workspace settings

Example request

Replace {company}, <token>, and any other placeholders with your values.

bash

curl --request POST \
  --url 'https://{company}.api.tellagen.com/api/v1/settings/webhooks/{id}/pause' \
  --header 'Authorization: Bearer <token>'

Success: 200

Returns the paused subscription.

Success response JSON

json

{
  "webhook": {
    "id": "22222222-2222-4222-8222-222222222222",
    "url": "https://hooks.example.test",
    "event_types": [
      "incident.created"
    ],
    "status": "paused",
    "created_at": "2026-09-14T10:00:00Z",
    "updated_at": "2026-09-14T10:02:00Z",
    "last_success_at": null,
    "last_failure_at": null
  }
}

Parameters, headers, and fields

Operation ID: pauseWebhookSubscription

Path parameters

Path parameters
Field	Description
`id` string Required	A webhook subscription ID returned by this API.

Response `200`

Returns the paused subscription.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`webhook` object Always returned	A workspace webhook subscription.
`webhook.id` string Always returned	The webhook subscription ID.
`webhook.name` string Sometimes returned	An optional display name for the webhook subscription. Maximum length: 100 characters.
`webhook.url` string Always returned	The HTTPS scheme and host of the destination. Responses omit the path and query string.
`webhook.event_types` string[] Always returned	The event types that the subscription receives. Minimum items: 1. · Items must be unique. Possible values: `"incident.created"`
`webhook.status` string Always returned	The delivery state of the subscription. Possible values: `"active""paused""revoked"`
`webhook.created_at` string (RFC 3339) Always returned	The time when the subscription was created.
`webhook.updated_at` string (RFC 3339) Always returned	The time when the subscription last changed.
`webhook.verified_at` string (RFC 3339) Sometimes returned	The time of the receiver check. Absent until verified. Active subscriptions require this value.
`webhook.last_success_at` string (RFC 3339) \| null Always returned	The time of the most recent successful delivery. The value is null before a successful delivery.
`webhook.last_failure_at` string (RFC 3339) \| null Always returned	The time of the most recent failed delivery. The value is null before a failed delivery.
`secret` string Sometimes returned	The signing secret. The API returns this field only after create or secret rotation.

Errors and recovery (7)

If the result is unknown, read the resource before another attempt. The error details explain the next step. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Resume a webhook subscription

POST/api/v1/settings/webhooks/{id}/resume

Starts delivery for a paused, verified subscription. An unverified receiver returns HTTP 409. A revoked subscription cannot resume.

Required scope: webhooks:manage
Also required: Manage workspace settings

Example request

Replace {company}, <token>, and any other placeholders with your values.

bash

curl --request POST \
  --url 'https://{company}.api.tellagen.com/api/v1/settings/webhooks/{id}/resume' \
  --header 'Authorization: Bearer <token>'

Success: 200

Returns the active subscription.

Success response JSON

json

{
  "webhook": {
    "id": "22222222-2222-4222-8222-222222222222",
    "url": "https://hooks.example.test",
    "event_types": [
      "incident.created"
    ],
    "status": "active",
    "created_at": "2026-09-14T10:00:00Z",
    "updated_at": "2026-09-14T10:03:00Z",
    "last_success_at": null,
    "last_failure_at": null
  }
}

Parameters, headers, and fields

Operation ID: resumeWebhookSubscription

Path parameters

Path parameters
Field	Description
`id` string Required	A webhook subscription ID returned by this API.

Response `200`

Returns the active subscription.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`webhook` object Always returned	A workspace webhook subscription.
`webhook.id` string Always returned	The webhook subscription ID.
`webhook.name` string Sometimes returned	An optional display name for the webhook subscription. Maximum length: 100 characters.
`webhook.url` string Always returned	The HTTPS scheme and host of the destination. Responses omit the path and query string.
`webhook.event_types` string[] Always returned	The event types that the subscription receives. Minimum items: 1. · Items must be unique. Possible values: `"incident.created"`
`webhook.status` string Always returned	The delivery state of the subscription. Possible values: `"active""paused""revoked"`
`webhook.created_at` string (RFC 3339) Always returned	The time when the subscription was created.
`webhook.updated_at` string (RFC 3339) Always returned	The time when the subscription last changed.
`webhook.verified_at` string (RFC 3339) Sometimes returned	The time of the receiver check. Absent until verified. Active subscriptions require this value.
`webhook.last_success_at` string (RFC 3339) \| null Always returned	The time of the most recent successful delivery. The value is null before a successful delivery.
`webhook.last_failure_at` string (RFC 3339) \| null Always returned	The time of the most recent failed delivery. The value is null before a failed delivery.
`secret` string Sometimes returned	The signing secret. The API returns this field only after create or secret rotation.

Errors and recovery (7)

If the result is unknown, read the resource before another attempt. The error details explain the next step. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Revoke a webhook subscription

POST/api/v1/settings/webhooks/{id}/revoke

Revokes a webhook subscription and cancels its pending deliveries. A revoked subscription cannot resume.

Required scope: webhooks:manage
Also required: Manage workspace settings

Example request

Replace {company}, <token>, and any other placeholders with your values.

bash

curl --request POST \
  --url 'https://{company}.api.tellagen.com/api/v1/settings/webhooks/{id}/revoke' \
  --header 'Authorization: Bearer <token>'

Success: 200

Returns the revoked subscription.

Success response JSON

json

{
  "webhook": {
    "id": "22222222-2222-4222-8222-222222222222",
    "url": "https://hooks.example.test",
    "event_types": [
      "incident.created"
    ],
    "status": "revoked",
    "created_at": "2026-09-14T10:00:00Z",
    "updated_at": "2026-09-14T10:04:00Z",
    "last_success_at": null,
    "last_failure_at": null
  }
}

Parameters, headers, and fields

Operation ID: revokeWebhookSubscription

Path parameters

Path parameters
Field	Description
`id` string Required	A webhook subscription ID returned by this API.

Response `200`

Returns the revoked subscription.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`webhook` object Always returned	A workspace webhook subscription.
`webhook.id` string Always returned	The webhook subscription ID.
`webhook.name` string Sometimes returned	An optional display name for the webhook subscription. Maximum length: 100 characters.
`webhook.url` string Always returned	The HTTPS scheme and host of the destination. Responses omit the path and query string.
`webhook.event_types` string[] Always returned	The event types that the subscription receives. Minimum items: 1. · Items must be unique. Possible values: `"incident.created"`
`webhook.status` string Always returned	The delivery state of the subscription. Possible values: `"active""paused""revoked"`
`webhook.created_at` string (RFC 3339) Always returned	The time when the subscription was created.
`webhook.updated_at` string (RFC 3339) Always returned	The time when the subscription last changed.
`webhook.verified_at` string (RFC 3339) Sometimes returned	The time of the receiver check. Absent until verified. Active subscriptions require this value.
`webhook.last_success_at` string (RFC 3339) \| null Always returned	The time of the most recent successful delivery. The value is null before a successful delivery.
`webhook.last_failure_at` string (RFC 3339) \| null Always returned	The time of the most recent failed delivery. The value is null before a failed delivery.
`secret` string Sometimes returned	The signing secret. The API returns this field only after create or secret rotation.

Errors and recovery (7)

If the result is unknown, read the resource before another attempt. The error details explain the next step. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Rotate a webhook secret

POST/api/v1/settings/webhooks/{id}/rotate-secret

Creates a new signing secret for the subscription. The API returns the new secret once.

Tellagen signs deliveries with the new secret and the previous secret for 24 hours. Update the receiver during this period.

Required scope: webhooks:manage
Also required: Manage workspace settings

Example request

Replace {company}, <token>, and any other placeholders with your values.

bash

curl --request POST \
  --url 'https://{company}.api.tellagen.com/api/v1/settings/webhooks/{id}/rotate-secret' \
  --header 'Authorization: Bearer <token>'

Success: 200

Returns the subscription and the new signing secret. The secret appears only in this response.

Success response JSON

json

{
  "webhook": {
    "id": "22222222-2222-4222-8222-222222222222",
    "url": "https://hooks.example.test",
    "event_types": [
      "incident.created"
    ],
    "status": "active",
    "created_at": "2026-09-14T10:00:00Z",
    "updated_at": "2026-09-14T10:05:00Z",
    "last_success_at": null,
    "last_failure_at": null
  },
  "secret": "whsec_new_example_secret_value"
}

Parameters, headers, and fields

Operation ID: rotateWebhookSecret

Path parameters

Path parameters
Field	Description
`id` string Required	A webhook subscription ID returned by this API.

Response `200`

Returns the subscription and the new signing secret. The secret appears only in this response.

“Always returned” applies when the parent object exists. The value can be null. Child fields describe each array item.

Response fields
Field	Description
`webhook` object Always returned	A workspace webhook subscription.
`webhook.id` string Always returned	The webhook subscription ID.
`webhook.name` string Sometimes returned	An optional display name for the webhook subscription. Maximum length: 100 characters.
`webhook.url` string Always returned	The HTTPS scheme and host of the destination. Responses omit the path and query string.
`webhook.event_types` string[] Always returned	The event types that the subscription receives. Minimum items: 1. · Items must be unique. Possible values: `"incident.created"`
`webhook.status` string Always returned	The delivery state of the subscription. Possible values: `"active""paused""revoked"`
`webhook.created_at` string (RFC 3339) Always returned	The time when the subscription was created.
`webhook.updated_at` string (RFC 3339) Always returned	The time when the subscription last changed.
`webhook.verified_at` string (RFC 3339) Sometimes returned	The time of the receiver check. Absent until verified. Active subscriptions require this value.
`webhook.last_success_at` string (RFC 3339) \| null Always returned	The time of the most recent successful delivery. The value is null before a successful delivery.
`webhook.last_failure_at` string (RFC 3339) \| null Always returned	The time of the most recent failed delivery. The value is null before a failed delivery.
`secret` string Sometimes returned	The signing secret. The API returns this field only after create or secret rotation.

Errors and recovery (7)

If the result is unknown, read the resource before another attempt. The error details explain the next step. Retries and updates

Error responses (7)

400 401 403 404 409 429 500

400: The API rejected the request because its syntax or one of its values is invalid.
401: The request does not contain valid authentication.
403: Authentication succeeded, but the caller lacks the required API scope or workspace permission.
404: The requested resource does not exist or is not available to the caller.
409: The request conflicts with the current resource state. idempotency_key_reused means that the key belongs to different request content. idempotency_in_progress means that an identical request is still in progress. idempotency_outcome_unknown means that an earlier request may have completed, but its result could not be stored and must not be retried automatically.
429: The request exceeded an applicable sliding limit. Free API keys allow 20 requests per second and 600 requests per 60 seconds. Team API keys allow 100 requests per second and 3,000 requests per 60 seconds. Browser users allow 100 requests per second. Browser company allows 500 requests per second and 5,000 requests per 10 seconds. Browser company means the sum of user traffic for one company. Anonymous client IPs allow 20 requests per second and 200 requests per 10 seconds. The rate limiter does not count requests that it rejects.
500: An internal server error prevented completion of the request.

Read this resource as Markdown · OpenAPI specification

Webhooks

Endpoints

List webhook subscriptions

Example request

Success: 200

Response 200

Error responses (7)

Create a webhook subscription

Example request

Success: 201

Request body

Response 201

Error responses (7)

Verify a webhook receiver

Example request

Success: 200

Path parameters

Response 200

Error responses (7)

Pause a webhook subscription

Example request

Success: 200

Path parameters

Response 200

Error responses (7)

Resume a webhook subscription

Example request

Success: 200

Path parameters

Response 200

Error responses (7)

Revoke a webhook subscription

Example request

Success: 200

Path parameters

Response 200

Error responses (7)

Rotate a webhook secret

Example request

Success: 200

Path parameters

Response 200

Error responses (7)

Response `200`

Response `201`

Response `200`

Response `200`

Response `200`

Response `200`

Response `200`