Hooks | Furcata

Un hook es una suscripción que le indica a Furcata a dónde enviar un evento de mensaje. Registras un endpoint HTTPS, eliges un evento y Furcata llama a ese endpoint cuando el evento ocurre en la cuenta.

Crear una suscripción

Indica el endpoint y el evento que te interesa. El id de la suscripción lo asigna el servidor y se devuelve en la respuesta.

POST /v0/account/{account_id}/hooks

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

Respuesta

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

Campos de la solicitud:

target_url: obligatorio, debe comenzar con https:// y tener como máximo 2048 caracteres.
event: obligatorio, uno de message.delivered, message.failed o message.inbound.

La respuesta devuelve el id asignado por el servidor junto con los valores que enviaste.

Listar suscripciones

Devuelve todos los hooks registrados en la cuenta.

GET /v0/account/{account_id}/hooks

curl https://api.furcata.com/v0/account/acc_123/hooks \
  -H "Authorization: Bearer YOUR_FURCATA_TOKEN"

Respuesta

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

Eliminar una suscripción

Elimina la suscripción de forma permanente. El endpoint deja de recibir eventos de inmediato. Esto requiere el rol de propietario de la cuenta.

DELETE /v0/account/{account_id}/hooks/{hook_id}

curl -X DELETE https://api.furcata.com/v0/account/acc_123/hooks/hook_123 \
  -H "Authorization: Bearer YOUR_FURCATA_TOKEN"

Un evento por suscripción

Una suscripción nombra un solo evento. Si quieres los eventos delivered, failed e inbound, crea tres suscripciones, o apúntalas al mismo endpoint y ramifica según el campo event.

Errores

400 cuando falta target_url, no es HTTPS o event no es uno de los tres valores admitidos.
401 cuando el token falta o no se acepta.
403 cuando alguien que no es el propietario de la cuenta intenta eliminar.
404 cuando el id del hook no existe en esta cuenta.

Próximos pasos

Lee Eventos de webhook y payloads para saber qué llega a tu endpoint, y la descripción general de Webhooks para conocer el comportamiento de entrega.