API de Webhooks

Los webhooks permiten que tu aplicación reciba notificaciones en tiempo real cuando ocurren eventos en Dailybot. En lugar de hacer polling a la API, registras una URL a la que Dailybot llamará cada vez que ocurran los eventos suscritos.

Info

Para una guía completa sobre webhooks incluyendo tipos de eventos, formatos de payload y mejores prácticas, consulta la guía de WebHooks y Eventos.

Método	Endpoint	Descripción
POST	/v1/webhook-subscription/	Registrar una URL de webhook y suscribirla a eventos
DELETE	/v1/webhook-subscription/	Dar de baja un webhook
POST	/v1/webhook-subscription/sample/	Obtener un payload de ejemplo para un tipo de evento

Eventos Soportados

Evento	Descripción
`FOLLOWUPS_DAILY_FINISHED`	Ronda de check-in completada
`FORMS_RESPONSE_CREATED`	Nueva respuesta de formulario
`FORMS_RESPONSE_UPDATED`	Respuesta de formulario actualizada
`FORMS_RESPONSE_APPROVED`	Respuesta de formulario aprobada
`FORMS_RESPONSE_DENIED`	Respuesta de formulario denegada
`KUDOS_POSTED`	Kudos enviados
`WORKFLOW_FINISHED`	Workflow completado

Crear Suscripción de Webhook

POST /v1/webhook-subscription/

Registra una URL de webhook y la suscribe a eventos.

Parámetros del Cuerpo

Name	Type	Required	Description
`hook_url`	string	Required	URL que recibirá los payloads del webhook.
`subscriptions`	string o array de strings	Required	Tipo(s) de evento a los que suscribirse.
`subscribed_objects`	string o array de strings	Optional	IDs de objeto para acotar la suscripción (ej. UUID de formulario, ID de check-in). Por defecto: vacío.
`name`	string	Optional	Nombre legible para el hook.
`immediate_sample_event`	boolean	Optional	Si es true, envía un evento de ejemplo al hook inmediatamente después del registro. Por defecto: false.
`bearer`	string	Optional	Token Bearer opcional para autenticar las peticiones a tu hook.

Petición

curl -X POST "https://api.dailybot.com/v1/webhook-subscription/" \
  -H "X-API-KEY: tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "hook_url": "https://tu-servidor.com/webhook",
    "subscriptions": ["forms.response.created", "kudos.posted"],
    "name": "Mi webhook",
    "immediate_sample_event": false,
    "bearer": "tu-token-verificacion"
  }'

Response 200 OK

json

{
  "id": 123,
  "url": "https://tu-servidor.com/webhook"
}

Response 403 Forbidden

json

{}

Verificar Firmas del Webhook

Usa el parámetro bearer para establecer un token de verificación. Dailybot incluirá este token en el header Authorization de las peticiones del webhook para que tu servidor pueda verificar el origen de la petición.

Eliminar Suscripción de Webhook

DELETE /v1/webhook-subscription/

Da de baja un webhook. Deben proporcionarse hook_id y hook_url.

Parámetros del Cuerpo

Name	Type	Required	Description
`hook_id`	integer	Required	ID del hook registrado.
`hook_url`	string	Required	URL que fue registrada.

Petición

curl -X DELETE "https://api.dailybot.com/v1/webhook-subscription/" \
  -H "X-API-KEY: tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "hook_id": 123,
    "hook_url": "https://tu-servidor.com/webhook"
  }'

Response 200 OK

json

{
  "id": "organization-uuid",
  "url": "https://tu-servidor.com/webhook"
}

Response 403 Forbidden

json

{}

Obtener Payload de Ejemplo

POST /v1/webhook-subscription/sample/

Devuelve un payload de evento de ejemplo para un tipo de evento. Úsalo para previsualizar la estructura de los payloads de webhook.

Parámetros del Cuerpo

Name	Type	Required	Description
`event`	string	Required	Tipo de evento (ej. followups.response.completed, forms.response.created, kudos.posted, workflows.finished).
`subscribed_objects`	array	Optional	IDs de objeto a incluir en el ejemplo (ej. UUID de formulario o ID de check-in).

Petición

curl -X POST "https://api.dailybot.com/v1/webhook-subscription/sample/" \
  -H "X-API-KEY: tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"event": "kudos.posted"}'

Response 200 OK

json

[
  {
    "event": "kudos.posted",
    "event_timestamp": 1708852800,
    "hook": {
      "id": "",
      "name": ""
    },
    "body": {}
  }
]