Skip to content

Create a webhook

POST
/webhooks
curl --request POST \
--url https://optlo.com/api/v1/webhooks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'idempotency-key: example' \
--data '{ "url": "https://example.com/webhooks/optlo", "types": [ "message.created" ] }'

Requires webhooks:manage and the read scope for every selected event. Idempotency-Key is required and retained for 24 hours, scoped to this key and POST /webhooks. Retrying identical validated input returns the original response, including its signing secret. Different input returns 409. At most 50 subscriptions per workspace; creating more returns 402 limit_exceeded. Store the signing secret securely; list responses omit it. Active subscriptions receive matching new events asynchronously. Destinations must use HTTPS and a public DNS hostname.

Media typeapplication/json
Show child attributesHide child attributes
url
required

HTTPS endpoint with a public hostname. Credentials and URL fragments are not allowed.

string format: uri
<= 2048 characters
types
required

Event types to subscribe to. The API key must have the read scope for each type.

array of string
>= 1 items <= 7 items
Allowed values: user.email_captured conversation.created conversation.closed conversation.reopened conversation.escalated message.created note.created

Created

Media typeapplication/json
Show child attributesHide child attributes
id
required

Unique identifier for the webhook subscription.

string
url
required

HTTPS endpoint that receives matching events.

string
types
required

Event types this subscription receives.

array of string
Allowed values: user.email_captured conversation.created conversation.closed conversation.reopened conversation.escalated message.created note.created
createdAt
required

Time the subscription was created.

string format: date-time
status
required

Whether the subscription is active or disabled. Disabled subscriptions receive no new events.

string
Allowed values: active disabled
disabledAt
required

Time the subscription was disabled, or null while active.

nullable string format: date-time
disabledReason
required

Reason the subscription was disabled: manually, an HTTP 410 response, or repeated failures. Null while active.

nullable string
Allowed values: manual gone failures
signingSecret
required

Secret used to verify webhook signatures. Store it securely; only creation and retained idempotent retries return it.

string

Example

{
"id": "hook_mR9kL3xN6pB2vQ8z_B8kN4pR6xZ2",
"url": "https://example.com/webhooks/optlo",
"types": [
"message.created"
],
"createdAt": "2026-10-13T08:00:00.000Z",
"status": "active",
"disabledAt": null,
"disabledReason": null,
"signingSecret": "example_secret_replace_with_your_own_12345678"
}