Referencia: Webhooks

Generada desde el contrato OpenAPI

Esta referencia se genera directamente del contrato de la API, por lo que sus descripciones están en inglés. Puedes descargarlo en openapi.json. Las guías explican cómo usar estos endpoints.

Webhooks

Webhook endpoints and their deliveries.

Operaciones

GET/webhooksPOST/webhooksGET/webhooks/{webhook}DELETE/webhooks/{webhook}PATCH/webhooks/{webhook}POST/webhooks/{webhook}/rotate-secretPOST/webhooks/{webhook}/testGET/webhooks/{webhook}/deliveriesPOST/webhooks/{webhook}/deliveries/retry-failedGET/webhook-deliveries/{delivery}POST/webhook-deliveries/{delivery}/retry

---

List webhook endpoints

GET

/webhooks

Autorizaciones

bearerAuth

An API key created in the dashboard (Authorization: Bearer ). The scopes listed on each operation must be granted to the key: instances:read, instances:write, messages:read, messages:send, webhooks:read, webhooks:write.

Tipo

HTTP (bearer)

Respuestas

The endpoints, newest first. meta.configured is true when an endpoint is enabled and has delivered successfully.

Content-Type

application/json

{

  

"data": [

  

  

{

  

  

  

"id": "string",

  

  

  

"url": "string",

  

  

  

"description": "string",

  

  

  

"events": [

  

  

  

  

"string"

  

  

  

],

  

  

  

"status": "string",

  

  

  

"secret_hint": "string",

  

  

  

"last_delivery": {

  

  

  

  

"id": "string",

  

  

  

  

"status": "string",

  

  

  

  

"response_status": 0,

  

  

  

  

"at": "string"

  

  

  

},

  

  

  

"disabled_at": "string",

  

  

  

"disabled_reason": "string",

  

  

  

"created_at": "string",

  

  

  

"updated_at": "string"

  

  

}

  

],

  

"meta": {

  

  

"configured": true

  

}

}

GET

/webhooks

Ejemplos

---

Create a webhook endpoint

POST

/webhooks

The endpoint is created enabled. The signing secret is returned only in this response (and when it is rotated). Store it; later reads show only a hint.

Autorizaciones

bearerAuth

An API key created in the dashboard (Authorization: Bearer ). The scopes listed on each operation must be granted to the key: instances:read, instances:write, messages:read, messages:send, webhooks:read, webhooks:write.

Tipo

HTTP (bearer)

Cuerpo de la petición

application/json

{

  

"url": "string",

  

"events": [

  

  

"string"

  

],

  

"description": "string"

}

Respuestas

The endpoint, including its secret.

Content-Type

application/json

{

  

"data": {

  

  

"id": "string",

  

  

"url": "string",

  

  

"description": "string",

  

  

"events": [

  

  

  

"string"

  

  

],

  

  

"status": "string",

  

  

"secret_hint": "string",

  

  

"last_delivery": {

  

  

  

"id": "string",

  

  

  

"status": "string",

  

  

  

"response_status": 0,

  

  

  

"at": "string"

  

  

},

  

  

"disabled_at": "string",

  

  

"disabled_reason": "string",

  

  

"created_at": "string",

  

  

"updated_at": "string",

  

  

"secret": "string"

  

}

}

POST

/webhooks

Ejemplos

---

Get a webhook endpoint

GET

/webhooks/{webhook}

Autorizaciones

bearerAuth

An API key created in the dashboard (Authorization: Bearer ). The scopes listed on each operation must be granted to the key: instances:read, instances:write, messages:read, messages:send, webhooks:read, webhooks:write.

Tipo

HTTP (bearer)

Respuestas

The endpoint.

Content-Type

application/json

{

  

"data": {

  

  

"id": "string",

  

  

"url": "string",

  

  

"description": "string",

  

  

"events": [

  

  

  

"string"

  

  

],

  

  

"status": "string",

  

  

"secret_hint": "string",

  

  

"last_delivery": {

  

  

  

"id": "string",

  

  

  

"status": "string",

  

  

  

"response_status": 0,

  

  

  

"at": "string"

  

  

},

  

  

"disabled_at": "string",

  

  

"disabled_reason": "string",

  

  

"created_at": "string",

  

  

"updated_at": "string"

  

}

}

GET

/webhooks/{webhook}

Ejemplos

---

Delete a webhook endpoint

DELETE

/webhooks/{webhook}

Autorizaciones

bearerAuth

An API key created in the dashboard (Authorization: Bearer ). The scopes listed on each operation must be granted to the key: instances:read, instances:write, messages:read, messages:send, webhooks:read, webhooks:write.

Tipo

HTTP (bearer)

Respuestas

Deleted.

DELETE

/webhooks/{webhook}

Ejemplos

---

Update a webhook endpoint

PATCH

/webhooks/{webhook}

Change the url, the subscribed events, the description or the status (enabled or disabled). Every field is optional.

Autorizaciones

bearerAuth

An API key created in the dashboard (Authorization: Bearer ). The scopes listed on each operation must be granted to the key: instances:read, instances:write, messages:read, messages:send, webhooks:read, webhooks:write.

Tipo

HTTP (bearer)

Cuerpo de la petición

application/json

{

  

"url": "string",

  

"events": [

  

  

"string"

  

],

  

"description": "string",

  

"status": "string"

}

Respuestas

The updated endpoint.

Content-Type

application/json

{

  

"data": {

  

  

"id": "string",

  

  

"url": "string",

  

  

"description": "string",

  

  

"events": [

  

  

  

"string"

  

  

],

  

  

"status": "string",

  

  

"secret_hint": "string",

  

  

"last_delivery": {

  

  

  

"id": "string",

  

  

  

"status": "string",

  

  

  

"response_status": 0,

  

  

  

"at": "string"

  

  

},

  

  

"disabled_at": "string",

  

  

"disabled_reason": "string",

  

  

"created_at": "string",

  

  

"updated_at": "string"

  

}

}

PATCH

/webhooks/{webhook}

Ejemplos

---

Rotate the signing secret

POST

/webhooks/{webhook}/rotate-secret

Issues a new secret, returned only in this response. The previous secret stops being used immediately.

Autorizaciones

bearerAuth

An API key created in the dashboard (Authorization: Bearer ). The scopes listed on each operation must be granted to the key: instances:read, instances:write, messages:read, messages:send, webhooks:read, webhooks:write.

Tipo

HTTP (bearer)

Respuestas

The endpoint with its new secret.

Content-Type

application/json

{

  

"data": {

  

  

"id": "string",

  

  

"url": "string",

  

  

"description": "string",

  

  

"events": [

  

  

  

"string"

  

  

],

  

  

"status": "string",

  

  

"secret_hint": "string",

  

  

"last_delivery": {

  

  

  

"id": "string",

  

  

  

"status": "string",

  

  

  

"response_status": 0,

  

  

  

"at": "string"

  

  

},

  

  

"disabled_at": "string",

  

  

"disabled_reason": "string",

  

  

"created_at": "string",

  

  

"updated_at": "string",

  

  

"secret": "string"

  

}

}

POST

/webhooks/{webhook}/rotate-secret

Ejemplos

---

Send a test event

POST

/webhooks/{webhook}/test

Queues a webhook.test event to the endpoint. The endpoint must be enabled.

Autorizaciones

bearerAuth

An API key created in the dashboard (Authorization: Bearer ). The scopes listed on each operation must be granted to the key: instances:read, instances:write, messages:read, messages:send, webhooks:read, webhooks:write.

Tipo

HTTP (bearer)

Respuestas

The queued test delivery.

Content-Type

application/json

{

  

"data": {

  

  

"id": "string",

  

  

"webhook_id": "string",

  

  

"event": {

  

  

  

"id": "string",

  

  

  

"type": "string",

  

  

  

"occurred_at": "string"

  

  

},

  

  

"status": "string",

  

  

"attempts": 0,

  

  

"max_attempts": 0,

  

  

"next_retry_at": "string",

  

  

"response_status": 0,

  

  

"error_code": "string",

  

  

"last_attempt_at": "string",

  

  

"delivered_at": "string",

  

  

"created_at": "string"

  

}

}

POST

/webhooks/{webhook}/test

Ejemplos

---

List the deliveries of an endpoint

GET

/webhooks/{webhook}/deliveries

Newest first, with cursor pagination (follow meta.next_cursor).

Autorizaciones

bearerAuth

An API key created in the dashboard (Authorization: Bearer ). The scopes listed on each operation must be granted to the key: instances:read, instances:write, messages:read, messages:send, webhooks:read, webhooks:write.

Tipo

HTTP (bearer)

Parámetros

Query Parameters

status

Tipo

string

Valores válidos

"pending""retrying""success""failed""exhausted"

event

Event type, for example message.received.

Tipo

string

Longitud máx.

40

limit

Page size (default 25).

Tipo

integer

Mínimo

1

Máximo

100

cursor

Tipo

string

Respuestas

A page of deliveries.

Content-Type

application/json

{

  

"data": [

  

  

{

  

  

  

"id": "string",

  

  

  

"webhook_id": "string",

  

  

  

"event": {

  

  

  

  

"id": "string",

  

  

  

  

"type": "string",

  

  

  

  

"occurred_at": "string"

  

  

  

},

  

  

  

"status": "string",

  

  

  

"attempts": 0,

  

  

  

"max_attempts": 0,

  

  

  

"next_retry_at": "string",

  

  

  

"response_status": 0,

  

  

  

"error_code": "string",

  

  

  

"last_attempt_at": "string",

  

  

  

"delivered_at": "string",

  

  

  

"created_at": "string"

  

  

}

  

],

  

"meta": {

  

  

"next_cursor": "string",

  

  

"per_page": 0

  

}

}

GET

/webhooks/{webhook}/deliveries

Ejemplos

---

Retry failed deliveries

POST

/webhooks/{webhook}/deliveries/retry-failed

Re-queues up to 100 deliveries in status failed or exhausted for one more attempt. The endpoint must be enabled.

Autorizaciones

bearerAuth

An API key created in the dashboard (Authorization: Bearer ). The scopes listed on each operation must be granted to the key: instances:read, instances:write, messages:read, messages:send, webhooks:read, webhooks:write.

Tipo

HTTP (bearer)

Respuestas

How many deliveries were re-queued and how many still wait.

Content-Type

application/json

{

  

"data": {

  

  

"requeued": 0,

  

  

"remaining": 0

  

}

}

POST

/webhooks/{webhook}/deliveries/retry-failed

Ejemplos

---

Get a delivery with its attempts

GET

/webhook-deliveries/{delivery}

Includes the request that was sent (URL, payload and the non-secret headers; the signature and timestamp headers are not repeated) and the log of attempts.

Autorizaciones

bearerAuth

An API key created in the dashboard (Authorization: Bearer ). The scopes listed on each operation must be granted to the key: instances:read, instances:write, messages:read, messages:send, webhooks:read, webhooks:write.

Tipo

HTTP (bearer)

Respuestas

The delivery.

Content-Type

application/json

{

  

"data": {

  

  

"id": "string",

  

  

"webhook_id": "string",

  

  

"event": {

  

  

  

"id": "string",

  

  

  

"type": "string",

  

  

  

"occurred_at": "string"

  

  

},

  

  

"status": "string",

  

  

"attempts": 0,

  

  

"max_attempts": 0,

  

  

"next_retry_at": "string",

  

  

"response_status": 0,

  

  

"error_code": "string",

  

  

"last_attempt_at": "string",

  

  

"delivered_at": "string",

  

  

"created_at": "string",

  

  

"request": {

  

  

  

"url": "string",

  

  

  

"headers": {

  

  

  

  

"additionalProperties": "string"

  

  

  

},

  

  

  

"payload": {

  

  

  

}

  

  

},

  

  

"attempt_log": [

  

  

  

{

  

  

  

  

"attempt": 0,

  

  

  

  

"manual": true,

  

  

  

  

"response_status": 0,

  

  

  

  

"response_body": "string",

  

  

  

  

"duration_ms": 0,

  

  

  

  

"error_code": "string",

  

  

  

  

"at": "string"

  

  

  

}

  

  

]

  

}

}

GET

/webhook-deliveries/{delivery}

Ejemplos

---

Retry one delivery

POST

/webhook-deliveries/{delivery}/retry

Queues a manual attempt. Not allowed while the delivery is still being attempted or when its endpoint is disabled or deleted.

Autorizaciones

bearerAuth

An API key created in the dashboard (Authorization: Bearer ). The scopes listed on each operation must be granted to the key: instances:read, instances:write, messages:read, messages:send, webhooks:read, webhooks:write.

Tipo

HTTP (bearer)

Respuestas

The delivery, queued again.

Content-Type

application/json

{

  

"data": {

  

  

"id": "string",

  

  

"webhook_id": "string",

  

  

"event": {

  

  

  

"id": "string",

  

  

  

"type": "string",

  

  

  

"occurred_at": "string"

  

  

},

  

  

"status": "string",

  

  

"attempts": 0,

  

  

"max_attempts": 0,

  

  

"next_retry_at": "string",

  

  

"response_status": 0,

  

  

"error_code": "string",

  

  

"last_attempt_at": "string",

  

  

"delivered_at": "string",

  

  

"created_at": "string"

  

}

}

POST

/webhook-deliveries/{delivery}/retry

Ejemplos

---