Eventos y cargas útiles de webhooks

Una suscripción de webhook une una transición de estado de mensaje en una cuenta con un endpoint HTTPS. Cuando ocurre la transición, Furcata envía un cuerpo JSON a tu endpoint.

Las suscripciones se crean, se listan y se eliminan con los endpoints de hooks. Cada suscripción nombra exactamente un evento.

Eventos disponibles

message.delivered — un mensaje llegó a su destinatario.
message.failed — un mensaje no se pudo entregar.
message.inbound — se recibió un mensaje en uno de tus números.

Suscribirse a un evento

POST /account/{account_id}/hooks registra un endpoint para un evento y devuelve la suscripción, incluido el id asignado por el servidor que usarás para eliminarla después.

curl --request POST \
  --url 'https://api.furcata.com/v0/account/acc_123/hooks' \
  --header 'Authorization: Bearer YOUR_FURCATA_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "target_url": "https://example.com/webhooks/furcata",
    "event": "message.delivered"
  }'

{
  "id": "hook_123",
  "target_url": "https://example.com/webhooks/furcata",
  "event": "message.delivered"
}

Campos de la suscripción

target_url — obligatorio. El endpoint HTTPS al que se notifica. Debe empezar con https:// y tiene como máximo 2048 caracteres.
event — obligatorio. Uno de message.delivered, message.failed, message.inbound.
id — identificador de la suscripción asignado por el servidor. Léelo en la respuesta de creación y úsalo para eliminar la suscripción.

Un evento por suscripción

Una suscripción lleva un solo valor de evento. Para recibir más de una transición, crea una suscripción por cada evento.

Listar suscripciones

GET /account/{account_id}/hooks devuelve todas las suscripciones de la cuenta.

curl --request GET \
  --url 'https://api.furcata.com/v0/account/acc_123/hooks' \
  --header 'Authorization: Bearer YOUR_FURCATA_TOKEN'

Eliminar una suscripción

DELETE /account/{account_id}/hooks/{hook_id} elimina una suscripción de forma permanente. Eliminar una suscripción requiere el rol de propietario de la cuenta.

curl --request DELETE \
  --url 'https://api.furcata.com/v0/account/acc_123/hooks/hook_123' \
  --header 'Authorization: Bearer YOUR_FURCATA_TOKEN'

Errores

400 — falta target_url, no empieza con https://, o event no es uno de los tres valores admitidos.
401 — falta el encabezado Authorization o el token no es válido.
403 — quien llama no tiene permiso para administrar hooks en esta cuenta, o no es el propietario al eliminar.
404 — el id del hook no existe en esta cuenta.

Todos los errores usan el formato descrito en Errores e idempotencia.