Los webhooks son la forma principal de recibir notificaciones en tiempo real de la PSB. Con cada evento relevante (una factura recibida, un cambio de estado, una confirmación de entrega), la PSB envía una solicitud HTTP POST a su endpoint con los detalles del evento.

Usted registra un webhook (un "hook") en la PSB con una URL y un topic. La PSB envía entonces todos los eventos de ese topic a su URL. Cada evento contiene los datos relevantes como payload JSON.

Registre un hook a través de la API:

POST /api/v1/hook

Los principales elementos de configuración:

MLS (Message Level Status) es el sucesor del antiguo MLR y proporciona a la parte remitente información sobre la recepción y el procesamiento de un documento. MLS no está habilitado por defecto y debe configurarse por party a través de la capability reviews en la configuración SMP. Una vez habilitado, la PSB gestiona el MLS de forma automática: como Service Provider receptor, la PSB envía un mensaje MLS de vuelta al remitente tras la recepción y entrega.

Cuando usted envía documentos a través de la PSB, recibe la respuesta MLS de la parte receptora como evento webhook en el topic MessageLevelStatusReceived. El payload contiene entre otros:

Para recibir mensajes MLS, el hook de Peppol debe contener el campo mlsType. Los valores posibles son ALWAYS_SEND (siempre enviar MLS de vuelta) y FAILURE_ONLY (solo en caso de rechazo).

Consejo: puede recuperar el documento MLS completo a través de GET /api/v1-beta/{partyId}/generic/{documentId}/download, pero el payload del webhook generalmente contiene información suficiente.

La PSB protege todas las entregas de webhooks con firmas HMAC SHA256. En cada solicitud, la PSB envía el header:

X-EConnect-Signature: sha256={handtekening}

Para verificar la firma:

1. Tome el payload JSON en bruto de la solicitud.
2. Calcule el hash HMAC SHA256 con su clave secreta (la misma que especificó al crear el hook).
3. Compare su hash calculado con el valor del header X-EConnect-Signature.
4. Si coinciden, la solicitud es auténtica.

Compruebe también el campo sentOn en el payload. Si esta marca temporal tiene más de 5 minutos de antigüedad, rechace la solicitud. Esto previene replay attacks en las que una solicitud interceptada se reproduce posteriormente.

Además de la verificación HMAC, la PSB ofrece capas de seguridad adicionales:

• IP-whitelisting: limite las solicitudes entrantes a las IP de producción de la PSB (104.40.188.59 y 104.47.148.207)
• Autenticación OAuth webhook: la PSB puede autenticarse en su endpoint con credenciales OAuth2
• Mutual SSL: utilice certificados de cliente para autenticación TLS mutua

Si tiene múltiples hooks configurados, la PSB determina qué hook utilizar según:

1. Los hooks a nivel PartyId tienen prioridad sobre los hooks a nivel environment
2. Los topics específicos tienen prioridad sobre los wildcards
3. En caso de prioridad igual: el hook-id sirve como criterio de desempate

A continuación se indican los problemas más comunes con los webhooks y cómo resolverlos.

El PSB envía eventos webhook (p. ej. InvoiceReceived al recibir una factura electrónica) al endpoint configurado. Si ese endpoint es inaccesible — por un tiempo de espera, un error SSL o un error DNS como No such host is known — el PSB reintenta con retroceso exponencial durante 5 días (tiempo de espera 100 seg. por intento). Cada intento genera un evento HookSentRetry; tras 5 días sin respuesta 2xx, se emite HookSentError como estado final y el PSB deja de reintentar.

Consecuencia: una factura electrónica recibida no se entregará al cliente mientras el endpoint sea inaccesible, sin que el cliente lo note directamente. Acciones recomendadas:

• Configurar monitorización: suscribir un hook (p. ej. un mail-hook) al topic HookSentError para que un fallo de entrega definitivo se señalice activamente en lugar de pasar desapercibido. Considerar también HookSentRetry para detección temprana.
• Solucionar la causa raíz: en caso de error DNS, verificar y restaurar el registro DNS del dominio del endpoint; en caso de tiempos de espera, hacer que el endpoint responda más rápido (2xx en 100 seg., procesamiento pesado de forma asíncrona).
• Recuperar eventos perdidos: los eventos que fallaron durante la interrupción pueden recuperarse a través del endpoint de lotes. La ventana de reintento de 5 días significa que la recuperación oportuna dentro de ese período puede todavía compensar mediante entrega regular.

• Utilice siempre HTTPS para su endpoint webhook
• Implemente un procesamiento idempotente: en casos excepcionales, la PSB puede entregar un evento varias veces
• Devuelva rápidamente un código de estado 2xx: la PSB considera cualquier respuesta que no sea 2xx como un error y reintentará el evento
• Registre todos los eventos recibidos para depuración y auditoría
• Utilice un sistema de cola (queue) en su lado si el procesamiento requiere tiempo; confirme primero la recepción y procese después

¿Prefiere recuperar los documentos en masa? Consulte el batch hook.

• Batch hooks: recuperar documentos en masa
• Join hooks: combinar adjuntos
• Mailfrom hooks: e-mail como fuente de documentos
• Integración SFTP
• E-mail hooks: notificaciones por e-mail
• Recibir una factura a través de la API
• Visión general: el Procurement Service Bus (PSB)
• Métodos de integración