Webhooks

Suscripciones salientes a los eventos de la plataforma, su secreto de firma y los intentos de entrega que produjeron. Once tools — el recurso más grande.

Ver el modelo Webhook, el modelo WebhookDelivery y Seguridad de webhooks para la validación de la firma HMAC.

---

webhooks_list

Lectura · scope inbox/webhooks · permiso webhooks.list · GET /webhooks

Lista las suscripciones de webhook. Los secretos de firma nunca se devuelven.

Parámetro	Tipo	Descripción
cursor	string	Cursor opaco de una página anterior.
limit	integer	Tamaño de página, por defecto 25, máximo 100.
sort	string	Claves de ordenación, prefijo - para descendente.
status	active | inactive	Filtra por estado.
inbox_id	string (uuid)	Solo suscripciones restringidas a este inbox.
external_id	string	Filtra por el id en tu sistema.
created_at_gte / created_at_lte	string	Rango ISO 8601 sobre created_at.

webhooks_get

Lectura · scope inbox/webhooks · permiso webhooks.show · GET /webhooks/{id}

Obtiene un webhook por id interno o external_id.

Parámetro	Tipo	Descripción
id obligatorio	string	Id interno o external_id.

webhooks_create

Escritura · scope inbox/webhooks + write · permiso webhooks.create · POST /webhooks

Crea una suscripción de webhook. La respuesta lleva el signing_secret en claro exactamente una vez — muéstraselo al usuario de inmediato, no se puede volver a leer.

Parámetro	Tipo	Descripción
label obligatorio	string	Nombre visible, 1–120 caracteres.
url obligatorio	string	URL de destino.
external_id	string	Id del registro en tu sistema.
inbox_id	string (uuid) | null	Restringe la suscripción a un inbox; null significa todo el workspace.
subscribed_events	string[]	Slugs de evento a suscribir.
auth	none | basic | bearer | header	Esquema de autenticación usado al llamar a tu endpoint.
auth_basic_user	string	Usuario, para basic.
auth_basic_password	string	Contraseña, para basic.
auth_bearer_token	string	Token, para bearer.
auth_header_key	string	Nombre del header, para header.
auth_header_value	string	Valor del header, para header.
signing_secret	string	Trae tu propio secreto (whsec_…); se genera cuando se omite.
custom_metadata	object	JSON libre, de quien llama.
idempotency_key	string	Protección contra repeticiones, 8–255 caracteres.

webhooks_upsert

Escritura · scope inbox/webhooks + write · permiso webhooks.create · PUT /webhooks

Crea o actualiza un webhook, emparejado por id y luego external_id. Un bloque auth reemplaza por completo al almacenado; un signing_secret lo rota y se devuelve una vez.

Parámetro	Tipo	Descripción
id	string (uuid)	Empareja primero por id interno.
external_id	string	Clave de emparejamiento en tu sistema.
label	string	Nombre visible, 1–120 caracteres.
url	string	URL de destino.
inbox_id	string (uuid) | null	Restringe a un inbox, o null para el workspace.
subscribed_events	string[]	Slugs de evento a suscribir.
auth	none | basic | bearer | header	Esquema de autenticación.
auth_basic_user	string	Usuario, para basic.
auth_basic_password	string	Contraseña, para basic.
auth_bearer_token	string	Token, para bearer.
auth_header_key	string	Nombre del header, para header.
auth_header_value	string	Valor del header, para header.
signing_secret	string	Rota el secreto; se devuelve una vez.
custom_metadata	object	JSON libre.
idempotency_key	string	Protección contra repeticiones.

webhooks_update

Escritura · scope inbox/webhooks + write · permiso webhooks.update · PATCH /webhooks/{id}

Actualiza una suscripción de webhook en su sitio.

Parámetro	Tipo	Descripción
id obligatorio	string	Id interno o external_id.
label	string	Nombre visible, 1–120 caracteres.
url	string	URL de destino.
external_id	string	Id en tu sistema.
inbox_id	string (uuid) | null	Restringe a un inbox, o null para el workspace.
subscribed_events	string[]	Slugs de evento a suscribir.
auth	none | basic | bearer | header	Esquema de autenticación.
auth_basic_user	string	Usuario, para basic.
auth_basic_password	string	Contraseña, para basic.
auth_bearer_token	string	Token, para bearer.
auth_header_key	string	Nombre del header, para header.
auth_header_value	string	Valor del header, para header.
custom_metadata	object	JSON libre.

webhooks_delete

Destructiva · scope inbox/webhooks + write · permiso webhooks.delete · DELETE /webhooks/{id}

Elimina (soft-delete) una suscripción de webhook. Las entregas pendientes se detienen.

Parámetro	Tipo	Descripción
id obligatorio	string	Id interno o external_id.

webhooks_test

Destructiva · scope inbox/webhooks + write · permiso webhooks.test · POST /webhooks/{id}/test

Envía un webhook.ping sintético por la ruta real de firma y reintento, para que valides URL y autenticación. Responde 202.

Parámetro	Tipo	Descripción
id obligatorio	string	Id interno o external_id.
idempotency_key	string	Protección contra repeticiones, 8–255 caracteres.

webhooks_regenerate_secret

Destructiva · scope inbox/webhooks + write · permiso webhooks.rotate-secret · POST /webhooks/{id}/regenerate-secret

Rota el secreto de firma. El nuevo se devuelve una vez; el anterior sigue validando durante la ventana de gracia.

Parámetro	Tipo	Descripción
id obligatorio	string	Id interno o external_id.
idempotency_key	string	Protección contra repeticiones, 8–255 caracteres.

webhooks_deliveries_list

Lectura · scope inbox/webhooks · permiso webhooks.show · GET /webhooks/{id}/deliveries

Intentos de entrega de un webhook, con estado HTTP y número de intento.

Parámetro	Tipo	Descripción
id obligatorio	string	Id interno o external_id del webhook.
cursor	string	Cursor opaco de una página anterior.
limit	integer	Tamaño de página, por defecto 25, máximo 100.
sort	string	Claves de ordenación, prefijo - para descendente.
status	pending | success | failed	Filtra por estado de la entrega.
attempt	integer	Filtra por número de intento.
response_status	integer	Filtra por el estado HTTP que respondió tu endpoint.
system_event_id	string (uuid)	Solo entregas de este evento.
created_at_gte / created_at_lte	string	Rango ISO 8601 sobre created_at.

webhooks_deliveries_get

Lectura · scope inbox/webhooks · permiso webhooks.show · GET /webhooks/{id}/deliveries/{delivery_id}

Obtiene un intento de entrega, incluidos headers y cuerpos de solicitud y respuesta.

Parámetro	Tipo	Descripción
id obligatorio	string	Id interno o external_id del webhook.
delivery_id obligatorio	string (uuid)	Id de la entrega.

webhooks_deliveries_replay

Destructiva · scope inbox/webhooks + write · permiso webhooks.replay · POST /webhooks/{id}/deliveries/{delivery_id}/replay

Reenvía una entrega con una firma nueva. Responde 202.

Parámetro	Tipo	Descripción
id obligatorio	string	Id interno o external_id del webhook.
delivery_id obligatorio	string (uuid)	Id de la entrega.
idempotency_key	string	Protección contra repeticiones, 8–255 caracteres.