Configure webhooks in the PSB: topics, HMAC SHA256 security and IP whitelisting.
Webhooks are the primary way to receive real-time notifications from the PSB. For every relevant event (an invoice received, a status change, a delivery confirmation) the PSB sends an HTTP POST request to your endpoint with the details of the event.
You register a webhook (a "hook") in the PSB with a URL and a topic. The PSB then sends all events for that topic to your URL. Each event contains the relevant data as a JSON payload.
Register a hook via the API:
POST /api/v1/hook
The main configuration elements:
InvoiceReceived)Note: avoid rapidly deleting and recreating hooks for the same partyId and topic. Due to race conditions in task processing, this can temporarily result in no active hook, causing events not to be delivered. Wait briefly after deleting a hook before creating a new one, or use an update instead of delete + create.
InvoiceReceivedInvoiceSentInvoiceSentErrorInvoiceSentRetryInvoiceResponseReceivedMessageLevelStatusReceivedMessageLevelStatusSentOrderReceivedMLS (Message Level Status) is the successor to the older MLR and provides the sending party with feedback on the receipt and processing of a document. MLS is not enabled by default and must be configured per party via the reviews capability in the SMP configuration. Once MLS is enabled, the PSB handles it automatically: as the receiving Service Provider, the PSB sends an MLS message back to the sender after receipt and delivery.
When you send documents via the PSB yourself, you receive MLS feedback from the receiving party as a webhook event on the topic MessageLevelStatusReceived. The payload includes:
documentIdrefToDocumentIddetails.statusCodeAP (accepted), RE (rejected), AB (acknowledged)details.descriptionTo receive MLS messages, the Peppol hook must contain the mlsType field. The possible values are ALWAYS_SEND (always send MLS back) and FAILURE_ONLY (only on rejections).
Tip: you can retrieve the full MLS document via
GET /api/v1-beta/{partyId}/generic/{documentId}/download, but the webhook payload usually contains sufficient information.
The PSB secures all webhook deliveries with HMAC SHA256 signatures. With every request the PSB sends the header:
X-EConnect-Signature: sha256={signature}
To verify the signature:
X-EConnect-Signature header.Also check the sentOn field in the payload. If this timestamp is older than 5 minutes, reject the request. This prevents replay attacks where an intercepted request is replayed at a later time.
In addition to HMAC verification, the PSB offers extra security layers:
104.40.188.59 and 104.47.148.207)If you have multiple hooks configured, the PSB determines which hook is used based on:
Not every system can expose a webhook endpoint for incoming traffic. Think of on-premise ERP systems or secured networks without inbound internet connectivity. For these situations the PSB offers HTTPS inbound hooks.
Instead of the PSB sending an event to your URL, you reverse the flow: the PSB pushes documents to an internal endpoint using the provided credentials. You configure the action with the httpsin:// protocol:
httpsin://user:pass@inbound?token=$token$
The PSB uses the specified username and password to deliver the document. The $token$ placeholder is automatically replaced by the document token.
HTTPS inbound hooks are specifically designed for environments where the regular webhook API does not work because inbound internet traffic is not possible. In all other cases, standard webhooks are the recommended approach.
By default a hook triggers on every event for the configured topic. With filters you can refine this, so a hook only fires when the event meets a specific condition.
Filters use lambda expression syntax. You add the filter as a property on the hook configuration:
{
"topic": "InvoiceReceived",
"url": "https://jouw-endpoint.nl/webhook",
"filter": "sender == \"0106:12345678\" && verdict.StartsWith(\"acc\")"
}
In this example the hook only triggers if the sender is 0106:12345678 and the verdict starts with acc (accepted).
Common use cases:
verdict.StartsWith("rej"))&& and ||Filters are useful when you have multiple hooks on the same topic, but each system should only receive relevant events. This prevents unnecessary processing.
In addition to specific topics you can also use wildcard patterns to capture multiple event types with a single hook.
Send*InvoiceSent, InvoiceSentError, InvoiceSentRetry, etc.)*ReceivedInvoiceReceived, OrderReceived, InvoiceResponseReceived, etc.)Invoice*Wildcards are particularly useful for catch-all hooks, for example a monitoring or logging endpoint that should receive all events. You can also combine wildcards with specific topics on other hooks. The priority order ensures that a more specific hook always takes precedence over a wildcard.
Take the raw JSON body of the request, compute the HMAC SHA256 hash using the secret you specified when creating the hook and compare it with the value in the X-EConnect-Signature header (after the sha256= prefix). If they match, you know the request came from the PSB and was not modified in transit.
Verify that sentOn is no older than 5 minutes. If the timestamp is too old, reject the request. This prevents replay attacks where a previously intercepted request is resubmitted later, even if the signature is technically valid.
Implement idempotent processing on your side, because the PSB may deliver an event more than once in rare cases. Also return an HTTP 2xx status quickly: any other response counts as an error and triggers a retry. For heavy processing, confirm receipt first and then process via a queue.
Prefer to retrieve documents in bulk? Check out the batch hook.
View the webhook endpoints