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. 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

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

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.

• 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