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.

Le payload contient toujours au moins les champs suivants :

De nouveaux champs de premier niveau inconnus et des extensions dans details peuvent apparaître (payloads forward-compatible). Construisez le parser pour ignorer les champs inconnus au lieu de lever une erreur.

Dédupliquez les documents entrants sur Invoice/ID + partyId de l'expéditeur + issueDate du fichier XML récupéré. C'est la responsabilité de l'application réceptrice, pas de la PSB. La PSB garantit une livraison at-least-once de la notification elle-même, mais ne surveille pas les doublons de contenu dans un autre canal de facturation électronique.

Chaque payload se compose des champs généraux ci-dessus, complétés d'un bloc details spécifique au topic. Les exemples suivants proviennent de la documentation DevOps de la PSB et servent de référence pour construire ou tester un consumer de webhook.

{
  "topic": "InvoiceReceived",
  "partyId": "NL:KVK:12345678",
  "hookId": "1",
  "documentId": "5618b40a-822d-4e74-8894-b489617dbaa4",
  "message": "Invoice successfully received.",
  "details": {
    "id": "invoiceId",
    "sender": "0106:87654321",
    "createdBy": "peppol",
    "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1"
  },
  "createdOn": "2026-04-30T09:00:00.0000000+00:00",
  "sentOn": "2026-04-30T09:00:00.5000000+00:00"
}

{
  "topic": "InvoiceSent",
  "partyId": "NL:KVK:12345678",
  "hookId": "1",
  "documentId": "5618b40a-822d-4e74-8894-b489617dbaa4",
  "message": "Invoice successfully sent.",
  "details": {
    "id": "invoiceId",
    "recipient": "0106:87654321",
    "endpoint": "https://accp-ap.econnect.eu/as4/v1",
    "protocol": "As4",
    "attempt": "1",
    "messageId": "3e3b336c-6563-431c-93bc-6b109dedfcc5@econnect.eu",
    "sourceDocumentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
    "targetDocumentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1"
  },
  "createdOn": "2026-04-30T09:31:57.7444125+00:00",
  "sentOn": "2026-04-30T09:31:57.8703556+00:00"
}

InvoiceSentRetry et InvoiceSentError suivent la même structure. Pour Retry, attempt est incrémenté ; pour Error, le champ message décrit la cause finale.

{
  "topic": "MessageLevelStatusReceived",
  "partyId": "NL:KVK:12345678",
  "hookId": "mls",
  "documentId": "615a914f-4a4d-4b3a-a258-828efb2817a6",
  "refToDocumentId": "d5e3bc34-96c8-4daf-b260-b7b182fa4760",
  "message": "'MessageLevelStatus' received. Status: 'Accept' Description: 'Document is accepted'.",
  "details": {
    "statusCode": "AP",
    "status": "Accept",
    "description": "Document is accepted",
    "documentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:peppol:edec:mls:1.0::2.1",
    "profileId": "urn:peppol:edec:mls"
  },
  "createdOn": "2026-03-11T22:43:18.2766651+00:00",
  "sentOn": "2026-03-11T22:43:18.8225397+00:00"
}

Interprétez details.statusCode (AP accepted, RE rejected ou AB acknowledged), details.description (explication de la partie réceptrice) et refToDocumentId (référence au document d'origine).

{
  "topic": "MessageLevelStatusSent",
  "partyId": "NL:KVK:ECONNECTTS",
  "hookId": "mls",
  "documentId": "c4a31897-66ac-468c-a7e8-14a24f9af114",
  "refToDocumentId": "be7005ff-5555-41eb-afef-f5ffec2b29ed",
  "message": "'ApplicationResponse' successfully sent.",
  "details": {
    "statusCode": "AP",
    "status": "Accept",
    "description": "Document is accepted",
    "profileId": "urn:peppol:edec:mls",
    "sourceDocumentTypeId": "urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:peppol:edec:mls:1.0::2.1",
    "attempt": "1",
    "protocol": "As4"
  },
  "createdOn": "2026-03-12T21:12:20.1621727+00:00",
  "sentOn": "2026-03-12T21:12:20.3726218+00:00"
}

OrderSent et les autres topics de commande utilisent des structures comparables avec un bloc details spécifique. Construisez un parser qui ignore les champs inconnus : l'élément details est dynamique et peut contenir de nouveaux champs.

En v1-beta, un hook peut contenir un tableau output avec des règles qui déterminent quel topic est publié selon le résultat de l'action. Cela permet un routage dynamique sans que le code appelant connaisse lui-même la logique de repli.

Chaque règle de sortie comporte deux champs :

Le premier when correspondant détermine le topic résultant. Si aucune règle ne correspond, ou si le champ output est absent, le hook retombe sur les topics par défaut.

Un scénario courant est Peppol avec repli e-mail : un hook Peppol publie un topic Send*Fallback en cas d'erreur de livraison (HTTP 400, 404 ou 500), qu'un hook mail distinct écoute pour envoyer la facture par e-mail.

{
  "id": "peppol",
  "action": "peppol",
  "name": "peppol hook",
  "topics": ["Send*"],
  "output": [
    { "when": "400", "topic": "Send*Fallback" },
    { "when": "404", "topic": "Send*Fallback" },
    { "when": "500", "topic": "Send*Fallback" }
  ],
  "isActive": true
}

Lorsque le même hook mail écoute aussi explicitement Send* (en plus de Send*Fallback), il apparaît automatiquement comme canal peppol-fallback dans la recherche multi-canal queryRecipientParty. Le code appelant peut alors choisir ce canal via ?channel=peppol-fallback sur les endpoints d'envoi.

Les topics de sortie conditionnelle ne se limitent pas au repli e-mail. Le mécanisme fonctionne pour toute combinaison de topics et peut aussi router des codes d'erreur vers un hook SFTP ou un webhook externe.

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 la PSB. Recette : 51.144.92.226 et 13.81.124.198. Production : 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 : tri alphanumérique du hook-id (d'abord les ids entiers, puis le texte, par exemple 1 < 02 < 10 < dico < peppol)

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

Les libellés de statut, par exemple dans un daily digest ou un pipeline d'événements, signifient autre chose qu'un échec de retry webhook (HookSentError) :

En bref : drop hook présent, donc dropped (ignoré volontairement, pas de dead letter) ; aucun hook correspondant, donc dead letter.

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 jusqu'à 12 fois, réparties sur environ 6 jours (environ 137 heures, délai 100 sec. par tentative). Chaque tentative génère un événement HookSentRetry ; après ces tentatives 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 d'environ 6 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 → suivez le runbook HookSentError standard ci-dessous (DNS/SSL/timeout, journaux, monitoring, 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