Saltar al contenido principal
En lugar de consultar cada poco, tu servidor recibe un POST firmado cuando pasa algo en la clínica. Brelio firma las entregas con el esquema Standard Webhooks, así que cualquier librería de Standard Webhooks las verifica.
En esta versión el único evento al que puedes suscribirte es webhookEndpoint.tested, la entrega de prueba. Los eventos de citas y pacientes son los siguientes; GET /v1/webhook-event-types siempre lista los disponibles.

1. Lista los tipos de evento

Respuesta
privacy es operational o personal (sobre pacientes). Los eventos clínicos nunca se entregan por webhook. Los eventos personal solo se entregan mientras el área de datos patients de la clínica está activada; mientras está desactivada, los campos de pacientes de otros eventos llegan como null.

2. Crea el webhook

Tu clave necesita integrations.keys.manage. La URL debe ser https en un nombre de host público (sin direcciones IP ni localhost).
201 Created
Guarda secret ahora, en tu gestor de secretos: solo se muestra aquí y al rotarlo. Los webhooks se crean solo por REST, nunca por MCP, así que el secreto nunca llega a un modelo de IA.

3. Verifica cada entrega

Cada entrega es un POST con un cuerpo JSON y tres cabeceras:
La firma es base64(HMAC-SHA256(clave, "{webhook-id}.{webhook-timestamp}.{cuerpo sin procesar}")), donde clave es la parte de tu secreto después de whsec_, decodificada de base64. Para verificarla:
  1. Calcula la firma sobre los bytes sin procesar del cuerpo, antes de interpretar el JSON.
  2. Compárala en tiempo constante con cada entrada v1, de webhook-signature (separadas por espacios: durante una rotación del secreto hay dos).
  3. Rechaza marcas de tiempo a más de 5 minutos de tu reloj, para evitar reenvíos.
  4. Responde 2xx rápido; haz el trabajo después.
O usa las librerías oficiales de Standard Webhooks, que hacen las mismas comprobaciones:
Instálalas con npm install standardwebhooks o pip install standardwebhooks.

4. Envía una prueba

Respuesta
La prueba se entrega a este webhook, esté suscrito a lo que esté. Como mucho 5 pruebas por minuto por webhook (429 WEBHOOK_TEST_RATE_LIMITED).

El cuerpo de la entrega

Reintentos y duplicados

  • Una entrega tiene éxito cuando tu servidor responde 2xx en menos de 15 segundos. No se siguen redirecciones.
  • Una entrega fallida se reintenta a los 5 s, 5 min, 30 min, 2 h, 5 h, 10 h y después cada 12 h, durante 3 días.
  • Si no llega nada en 3 días, el webhook se desactiva y se avisa a los propietarios de la clínica. failingSince y disablesAt del webhook te avisan antes.
  • webhook-id es el id de la entrega y es el mismo en cada reintento y en un reenvío manual. Guarda los ids que ya procesaste y descarta los repetidos.
  • Las entregas pueden llegar desordenadas. Usa timestamp, o lee el registro desde la API, cuando el orden importe.

Diagnostica un webhook

recentDeliveries muestra de cada entrega su status (pending, succeeded, failed, skipped), attempts, lastStatusCode, lastError y nextAttemptAt. Cuando hayas arreglado tu servidor, reenvía una entrega ya en lugar de esperar:

Rota el secreto

La respuesta trae el nuevo secret. Durante 24 horas (previousSecretExpiresAt) las entregas se firman con los dos secretos, para que puedas desplegar el nuevo sin perder nada. Los receptores de arriba ya aceptan cualquiera de las dos firmas.

Elimínalo

Respuesta
Eliminarlo borra el webhook y su registro de entregas; no se envía nada más.