Webhooks API Reference

API ReferenceWebhooks

Search API docsAll documentation

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

MethodScope

Webhooks

Manage workspace webhook subscriptions and receive signed incident events.

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[].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[].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 workspace exceeded an active request limit.
500: An internal server error prevented completion of the request.

Create a webhook subscription

POST/api/v1/settings/webhooks

Creates a webhook subscription for the workspace. Use an HTTPS URL that resolves to a public address. The API returns the signing secret once.

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": "active",
    "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
`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.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.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 workspace exceeded an active request limit.
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.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.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 workspace exceeded an active request limit.
500: An internal server error prevented completion of the request.

Resume a webhook subscription

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

Starts new deliveries for a paused subscription. 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.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.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 workspace exceeded an active request limit.
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.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.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 workspace exceeded an active request limit.
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.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.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 workspace exceeded an active request limit.
500: An internal server error prevented completion of the request.

Read this resource as Markdown · OpenAPI specification

Webhooks

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)

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`