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:

¿Desea agregar un topic adicional (por ejemplo, InvoiceReceived) a un hook existente? Actualice la configuración webhook existente a través de la API /hook habitual para que el topic deseado esté incluido en el array topics:

{
  "topics": ["InvoiceReceived"]
}

Actualice el hook existente en lugar de eliminarlo y volver a crearlo. Eliminar y volver a crear introduce una race condition donde los eventos pueden no entregarse temporalmente (véase la advertencia anterior).

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. Como Service Provider receptor, sigue un webhook independiente con el topic MessageLevelStatusSent en cuanto la PSB envía en su nombre un MLS al SP remitente. Utilice este topic para supervisar si sus propias respuestas MLS emitidas se entregan correctamente.

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. Si varios hooks con filtros coinciden en el mismo topic: gana el filtro más largo (según el número de caracteres) -- por ejemplo, un filtro con una cláusula && adicional gana a un filtro más corto sin esa cláusula. Esto evita la entrega duplicada sin obligar a que los filtros sean mutuamente excluyentes.
4. En caso de prioridad igual: el hook-id sirve como criterio de desempate

Además de los topics específicos, también puede usar patrones wildcard para capturar varios tipos de eventos con un solo hook.

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

El PSB puede recibir una factura de compra sin reenviarla a la parte receptora. El topic InvoiceReceived significa que el PSB ha recibido la factura; sin un hook en ese topic, no se envía nada a un endpoint.

• La ausencia de errores de webhook no prueba que el hook funcione. HookSentError solo existe si hay un hook configurado que falla al entregar.
• Un hook puede haber sido eliminado mientras tanto. Una entrega exitosa anterior a la misma parte/endpoint prueba que el hook existió, no que sigue presente ahora. Verifique primero la configuración actual del hook en lugar de tratarlo como una configuración inicial.
• Una confirmación de recepción en el lado del remitente no es lo mismo que la entrega al software receptor.

Corrija un hook faltante actualizando el hook existente en lugar de eliminarlo y volver a crearlo.

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.

Primera línea: interrupción del lado del cliente vs. problema técnico (aceptación y producción)

HookSentError, un HTTP 404 repetido o "endpoint fuera de servicio"/"entorno de aceptación apagado" también puede deberse a que el cliente apaga temporalmente el endpoint de aceptación o producción (desarrollo, mantenimiento). Esto no es una incidencia de la plataforma eConnect.

1. Confirmar el síntoma: HookSentError, endpoint fuera de servicio o HTTP 404 en el endpoint webhook configurado por el cliente. A menudo visible como el texto exacto Response status code does not indicate success: 404 (Not Found) (normalmente una HttpRequestException de .NET en la solicitud saliente del hook). Este es un 404 del propio endpoint del cliente (apagado o ruta incorrecta), no el error Peppol PartyId not found al enviar (404 de SMP), ni un 404 de recurso REST del manejo de errores de la API.
2. Preguntar si la interrupción es intencionada y temporal (desarrolladores/cliente).
3. Confirmado temporal → anotar, sin más acción por parte de eConnect hasta que el endpoint vuelva a estar activo. Cuando el endpoint vuelva a devolver 2xx, los eventos perdidos pueden recuperarse a través del endpoint de lotes.
4. No intencionado o desconocido → seguir el runbook estándar de HookSentError anterior (DNS/SSL/tiempo de espera, registros, monitorización, recuperación por lotes).

• 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