Les webhooks sont le moyen principal de recevoir des notifications en temps réel de la PSB. Lors de chaque événement pertinent (une facture reçue, un changement de statut, une confirmation de livraison), la PSB envoie une requête HTTP POST vers votre endpoint avec les détails de l'événement.

Vous enregistrez un webhook (un "hook") dans la PSB avec une URL et un topic. La PSB envoie ensuite tous les événements de ce topic vers votre URL. Chaque événement contient les données pertinentes sous forme de payload JSON.

Enregistrez un hook via l'API :

POST /api/v1/hook

Les principaux éléments de configuration :

Vous souhaitez ajouter un topic supplémentaire (par ex. InvoiceReceived) à un hook existant ? Mettez à jour la configuration webhook existante via l'API /hook habituelle afin que le topic souhaité figure dans le tableau topics :

{
  "topics": ["InvoiceReceived"]
}

Mettez à jour le hook existant plutôt que de le supprimer et de le recréer. Supprimer et recréer introduit une race condition où les événements peuvent ne pas être livrés temporairement (voir l'avertissement ci-dessus).

Le MLS (Message Level Status) est le successeur de l'ancien MLR et fournit à la partie expéditrice un retour sur la réception et le traitement d'un document. Le MLS n'est pas activé par défaut et doit être configuré par party via la capability reviews dans la configuration SMP. Une fois le MLS activé, la PSB le gère automatiquement : en tant que Service Provider récepteur, la PSB renvoie un message MLS à l'expéditeur après réception et livraison.

Lorsque vous envoyez vous-même des documents via la PSB, vous recevez le retour MLS de la partie réceptrice sous forme d'événement webhook sur le topic MessageLevelStatusReceived. En tant que Service Provider récepteur, un webhook distinct avec le topic MessageLevelStatusSent suit dès que la PSB envoie en votre nom un MLS au SP expéditeur. Utilisez ce topic pour vérifier que vos propres réponses MLS sortantes sont bien livrées.

Le payload contient entre autres :

Pour recevoir des messages MLS, le hook Peppol doit contenir le champ mlsType. Les valeurs possibles sont ALWAYS_SEND (toujours renvoyer un MLS) et FAILURE_ONLY (uniquement en cas de rejet).

Conseil : vous pouvez récupérer le document MLS complet via GET /api/v1-beta/{partyId}/generic/{documentId}/download, mais le payload du webhook contient généralement suffisamment d'informations.

La PSB sécurise toutes les livraisons de webhooks avec des signatures HMAC SHA256. À chaque requête, la PSB envoie le header :

X-EConnect-Signature: sha256={handtekening}

Pour vérifier la signature :

1. Prenez le payload JSON brut de la requête.
2. Calculez le hash HMAC SHA256 avec votre clé secrète (la même que celle spécifiée lors de la création du hook).
3. Comparez votre hash calculé avec la valeur du header X-EConnect-Signature.
4. S'ils correspondent, la requête est authentique.

Vérifiez également le champ sentOn dans le payload. Si ce timestamp est antérieur de plus de 5 minutes, rejetez la requête. Cela prévient les replay attacks où une requête interceptée est rejouée ultérieurement.

En plus de la vérification HMAC, la PSB propose des couches de sécurité supplémentaires :

• IP-whitelisting : limitez les requêtes entrantes aux IP de production de la PSB (104.40.188.59 et 104.47.148.207)
• Authentification OAuth webhook : la PSB peut s'authentifier auprès de votre endpoint avec des credentials OAuth2
• Mutual SSL : utilisez des certificats clients pour une authentification TLS mutuelle

Si vous avez configuré plusieurs hooks, la PSB détermine quel hook utiliser selon :

1. Les hooks au niveau PartyId ont priorité sur les hooks au niveau environment
2. Les topics spécifiques ont priorité sur les wildcards
3. Si plusieurs hooks avec des filtres correspondent au même topic : le filtre le plus long (en nombre de caractères) gagne -- par exemple, un filtre avec une clause && supplémentaire gagne sur un filtre plus court sans cette clause. Cela évite une double livraison sans obliger les filtres à s'exclure mutuellement.
4. En cas de priorité égale : le hook-id sert de critère de départage

En plus des topics spécifiques, vous pouvez utiliser des motifs wildcard pour capturer plusieurs types d'événements avec un seul hook.

Voici les problèmes courants avec les webhooks et comment les résoudre.

Le PSB peut recevoir une facture d'achat sans la transmettre à la partie destinataire. Le topic InvoiceReceived signifie que le PSB a reçu la facture ; sans hook sur ce topic, rien n'est envoyé à un endpoint.

• L'absence d'erreurs webhook ne prouve pas que le hook fonctionne. HookSentError n'existe que si un hook est configuré et échoue à livrer.
• Un hook peut avoir été supprimé entre-temps. Une livraison réussie antérieure vers la même partie/endpoint prouve que le hook a existé, pas qu'il est toujours présent. Vérifier donc d'abord la configuration actuelle du hook plutôt que de traiter cela comme une configuration initiale.
• Un accusé de réception côté expéditeur n'équivaut pas à une livraison au logiciel destinataire.

Corrigez un hook manquant en mettant à jour le hook existant plutôt qu'en le supprimant et le recréant.

Le PSB envoie des événements webhook (p. ex. InvoiceReceived lors de la réception d'une facture électronique) à l'endpoint configuré. Si cet endpoint est inaccessible - en raison d'un délai d'attente, d'une erreur SSL ou d'une erreur DNS comme No such host is known - le PSB réessaie avec un recul exponentiel pendant 5 jours (délai 100 sec. par tentative). Chaque tentative génère un événement HookSentRetry ; après 5 jours sans réponse 2xx, HookSentError est émis comme statut final et le PSB cesse de réessayer.

Conséquence : une facture électronique reçue ne sera pas livrée au client tant que l'endpoint est inaccessible, sans que le client s'en aperçoive directement. Actions recommandées :

• Mettre en place une surveillance : abonner un hook (p. ex. un mail-hook) au topic HookSentError afin qu'un échec de livraison définitif soit signalé activement plutôt que de passer inaperçu. Envisager également HookSentRetry pour une détection précoce.
• Corriger la cause racine : en cas d'erreur DNS, vérifier et restaurer l'enregistrement DNS du domaine de l'endpoint ; en cas de délais, faire répondre l'endpoint plus rapidement (2xx en 100 sec., traitement lourd de manière asynchrone).
• Récupérer les événements manqués : les événements échoués pendant l'interruption peuvent être récupérés via le endpoint batch. La fenêtre de 5 jours signifie qu'une réparation rapide dans ce délai peut encore rattraper la livraison normale.

Première ligne : interruption côté client vs. problème technique (acceptation et production)

HookSentError, un HTTP 404 répété ou « endpoint hors ligne »/« environnement d'acceptation désactivé » peut aussi provenir du fait que le client désactive temporairement l'endpoint d'acceptation ou de production (développement, maintenance). Ce n'est pas un incident de la plateforme eConnect.

1. Confirmer le symptôme : HookSentError, endpoint hors ligne ou HTTP 404 sur l'endpoint webhook configuré par le client. Souvent visible sous la forme exacte Response status code does not indicate success: 404 (Not Found) (généralement une HttpRequestException .NET lors de la requête hook sortante). Il s'agit d'un 404 provenant de l'endpoint du client lui-même (hors ligne ou chemin incorrect), pas de l'erreur Peppol PartyId not found lors de l'envoi (404 SMP), ni d'un 404 de ressource REST issu de la gestion des erreurs de l'API.
2. Demander si l'interruption est intentionnelle et temporaire (développeurs/client).
3. Confirmé temporaire → noter, aucune action supplémentaire côté eConnect jusqu'à ce que l'endpoint soit de nouveau opérationnel. Une fois que l'endpoint renvoie de nouveau du 2xx, les événements manqués peuvent être récupérés via le endpoint batch.
4. Non intentionnel ou inconnu → suivre le runbook standard HookSentError ci-dessus (DNS/SSL/délai, journaux, surveillance, récupération batch).

• Utilisez toujours HTTPS pour votre endpoint webhook
• Implémentez un traitement idempotent : dans de rares cas, la PSB peut livrer un événement plusieurs fois
• Retournez rapidement un code de statut 2xx : la PSB considère toute réponse non-2xx comme une erreur et réessaiera l'événement
• Journalisez tous les événements reçus pour le débogage et l'audit
• Utilisez un système de file d'attente (queue) de votre côté si le traitement prend du temps ; confirmez d'abord la réception, puis traitez ensuite

Vous préférez récupérer les documents en masse ? Consultez le batch hook.

• Batch hooks : récupérer des documents en masse
• Join hooks : fusionner des pièces jointes
• Mailfrom hooks : e-mail comme source de documents
• Intégration SFTP
• E-mail hooks : notifications par e-mail
• Recevoir une facture via l'API
• Aperçu : le Procurement Service Bus (PSB)
• Aperçu des méthodes d'intégration