Vigilar empresas mediante webhooks
Verificar a un tercero una sola vez no basta: un cliente se muda, un proveedor cesa su actividad. Los webhooks te avisan en lugar de obligarte a consultar la API.
El problema#
Una cartera de clientes o proveedores envejece. Las direcciones cambian, las denominaciones evolucionan, las empresas cesan su actividad. La primera idea es consultar la API cada noche para todas las empresas de la cartera: consume cuota, y la mayoría de las respuestas no cambian nada.
Los webhooks invierten la lógica: declaras una vez los números que vigilar y es la API la que llama a tu servidor cuando una ficha vigilada cambia en el registro.
Los datos de la API que responden#
POST /webhook: crea un webhook (nombre, URL de recepción, números que vigilar). El secret de firma HMAC solo se devuelve una vez, en esta respuesta.POST /webhook/{id}/subscriptionsyDELETE /webhook/{id}/subscriptions: añaden o retiran números de empresa o de establecimiento.GET /webhook/{id}/subscriptions: la lista de números que vigila un webhook.POST /webhook/{id}/trigger: envía una entrega de prueba para comprobar tu receptor y tu verificación de firma.GET /webhook/{id}/events: el registro de los últimos 100 intentos de entrega, con estado, código de respuesta y marca de tiempo.PATCH /webhook/{id}/hmac-secret: renueva el secret de firma; el anterior deja de ser válido de inmediato.
Cada evento indica su tipo (creación, modificación o desactivación de la ficha, o entrega de prueba), el número afectado y el tipo de entidad, y va firmado con el secret del webhook. La verificación de la firma se describe paso a paso en la guía de webhooks.
Ejemplo de petición#
"tok-comment"># 1. Create the webhook with a first enterprise to watch
"tok-comment"># (the hmacSecret is returned only once: store it)
curl -X POST https://companybelgium.be/api/v2/webhook \
-H "X-API-Key: $API_BCE_KEY" -H "X-API-Secret: $API_BCE_SECRET" \
-H "Content-Type: application/json" \
-d '{"name":"Portfolio watch","url":"https://example.be/hooks/bce","entityNumbers":["1033.022.383"]}'
"tok-comment">
# 2. Add more enterprise numbers later
curl -X POST https://companybelgium.be/api/v2/webhook/$WEBHOOK_ID/subscriptions \
-H "X-API-Key: $API_BCE_KEY" -H "X-API-Secret: $API_BCE_SECRET" \
-H "Content-Type: application/json" \
-d '{"entityNumbers":["<another enterprise number>"]}'
"tok-comment">
# 3. Send a test delivery, then read the delivery log
curl -X POST https://companybelgium.be/api/v2/webhook/$WEBHOOK_ID/trigger \
-H "X-API-Key: $API_BCE_KEY" -H "X-API-Secret: $API_BCE_SECRET"
curl https://companybelgium.be/api/v2/webhook/$WEBHOOK_ID/events \
-H "X-API-Key: $API_BCE_KEY" -H "X-API-Secret: $API_BCE_SECRET"Implementación recomendada#
- Verifica la firma de cada entrega antes de tenerla en cuenta, sobre el cuerpo en bruto de la petición.
- Responde rápido con un código 2xx y procesa después el evento en segundo plano: vuelve a leer la ficha con
GET /enterprise/{num}para conocer su nuevo estado. - Haz que el procesamiento sea idempotente: una misma entrega puede llegar más de una vez.
- Añade los números al webhook cuando un cliente o proveedor entra en tu cartera y retíralos cuando termina la relación.
- Consulta el registro de entregas cuando tu receptor no estuvo disponible y lanza una entrega de prueba después de cada despliegue.
Límites que conviene conocer#
- Los eventos siguen las actualizaciones publicadas por la BCE: llegan después de que un cambio se inscriba en el registro, no en el momento de la decisión.
- Un webhook indica que una ficha ha cambiado; para conocer el nuevo valor de un campo, vuelve a leer la ficha.
- Las entregas fallidas se reintentan, pero un receptor que permanece inaccesible puede perder eventos: el registro de los últimos 100 intentos ayuda a recuperarlos.
- Los webhooks vigilan números concretos. No señalan las nuevas empresas de un sector o de una región.
Preguntas frecuentes#
¿Qué cambios activan un webhook?
La creación, modificación o desactivación de la ficha de una empresa o establecimiento vigilado, tal como lo publica la BCE, además de las entregas de prueba que tú lances.
¿Cómo proteger el receptor?
Cada entrega va firmada con HMAC usando el secret del webhook. Verifica la firma sobre el cuerpo en bruto antes de procesar el evento y renueva el secret si se filtra.
¿Se pueden vigilar establecimientos?
Sí. Las suscripciones aceptan números de empresa y de establecimiento.
Llevarlo a la práctica
Crea una clave en el portal de desarrolladores y sigue después la documentación de referencia de cada endpoint citado.
Documentación de referencia