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 necesitaintegrations.keys.manage. La URL debe ser https en un nombre de host público (sin direcciones IP ni localhost).
201 Created
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 unPOST con un cuerpo JSON y tres cabeceras:
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:
- Calcula la firma sobre los bytes sin procesar del cuerpo, antes de interpretar el JSON.
- Compárala en tiempo constante con cada entrada
v1,dewebhook-signature(separadas por espacios: durante una rotación del secreto hay dos). - Rechaza marcas de tiempo a más de 5 minutos de tu reloj, para evitar reenvíos.
- Responde
2xxrápido; haz el trabajo después.
npm install standardwebhooks o pip install standardwebhooks.
4. Envía una prueba
Respuesta
429 WEBHOOK_TEST_RATE_LIMITED).
El cuerpo de la entrega
Reintentos y duplicados
- Una entrega tiene éxito cuando tu servidor responde
2xxen 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.
failingSinceydisablesAtdel webhook te avisan antes. webhook-ides 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
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