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:

Want to add an extra topic (e.g. InvoiceReceived) to an existing hook? Update the existing webhook configuration via the regular /hook API so that the desired topic is included in the topics array:

{
  "topics": ["InvoiceReceived"]
}

Update the existing hook instead of deleting and recreating it. Deleting and recreating introduces a race condition where events may temporarily not be delivered (see the warning above).

MLS (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. As the receiving Service Provider, a separate webhook with topic MessageLevelStatusSent follows once the PSB sends out an MLS on your behalf to the sending SP. Use this topic to monitor whether your own self-issued MLS responses are delivered correctly.

The payload includes:

To 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:

1. Take the raw JSON payload of the request.
2. Calculate the HMAC SHA256 hash using your secret key (the same one you provided when creating the hook).
3. Compare your calculated hash with the value in the X-EConnect-Signature header.
4. If they match, the request is authentic.

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:

• IP whitelisting: restrict incoming requests to the PSB production IPs (104.40.188.59 and 104.47.148.207)
• OAuth webhook authentication: the PSB can authenticate with your endpoint using OAuth2 credentials
• Mutual SSL: use client certificates for mutual TLS authentication

If you have multiple hooks configured, the PSB determines which hook is used based on:

1. PartyId-level hooks take precedence over environment-level hooks
2. Specific topics take precedence over wildcards
3. If multiple hooks with filters match the same topic: the longest filter (by character count) wins -- for example, a filter with an extra && clause wins over a shorter filter without that clause. This prevents duplicate delivery without requiring filters to be mutually exclusive.
4. At equal priority: hook-id as tiebreaker

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.

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:

• Only trigger on rejections (verdict.StartsWith("rej"))
• Filter by a specific sender or recipient
• Combine multiple conditions with && and ||

In addition to specific topics you can also use wildcard patterns to capture multiple event types with a single hook.

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.

Below are common webhook issues and how to resolve them.

The PSB can receive a purchase invoice without forwarding it to the receiving party. Topic InvoiceReceived means the PSB has received the invoice; without a hook on that topic, nothing is sent to an endpoint.

• No webhook errors is not proof that the hook works. HookSentError only exists if a hook is configured that fails to deliver.
• A hook may have been removed in the meantime. Earlier successful delivery to the same party/endpoint proves the hook existed, not that it is still there now. Always check the current hook configuration first instead of treating this as a first-time setup issue.
• A receipt confirmation at the sender's side is not the same as delivery to the receiving software.

Fix a missing hook by updating the existing hook instead of deleting and recreating it.

The PSB sends webhook events (e.g. InvoiceReceived when an e-invoice is received) to the configured endpoint. If that endpoint is unreachable — due to a timeout, an SSL error or a DNS error such as No such host is known — the PSB retries with exponential backoff for 5 days (timeout 100 sec per attempt). Each attempt triggers a HookSentRetry event; after 5 days without a 2xx response, HookSentError is issued as the final status and the PSB stops retrying.

Consequence: a received e-invoice will not be delivered to the customer as long as the endpoint is unreachable, without the customer noticing directly. Recommended follow-up:

• Set up monitoring: subscribe a hook (e.g. a mail hook) to the HookSentError topic so that a definitive delivery failure is actively signalled rather than silently dropped. Consider also subscribing to HookSentRetry for early detection.
• Fix the root cause: for a DNS error, check and restore the DNS record for the endpoint domain; for timeouts, make the endpoint respond faster (2xx within 100 sec, offload heavy processing asynchronously).
• Recover missed events: events that failed during the outage can still be retrieved via the batch endpoint. The 5-day retry window means that timely recovery within that period can still catch up via regular delivery.

First line: customer-side downtime vs. technical issue (acceptance and production)

HookSentError, a repeated HTTP 404, or "endpoint is offline"/"acceptance environment is down" can also occur because the customer temporarily switches off the acceptance or production endpoint (development, maintenance). That is not an eConnect platform incident.

1. Confirm the symptom: HookSentError, endpoint offline, or HTTP 404 on the webhook endpoint configured by the customer. Often visible as the exact text Response status code does not indicate success: 404 (Not Found) (typically a .NET HttpRequestException on the outgoing hook request). This is a 404 from the customer's own endpoint (down or wrong path), not the Peppol PartyId not found error when sending (SMP 404), and not a REST resource 404 from the API's error handling.
2. Ask whether the downtime is intentional and temporary (developers/customer).
3. Confirmed temporary → note it, no further action on eConnect's side until the endpoint is back up. Once the endpoint returns 2xx again, missed events can be retrieved via the batch endpoint.
4. Not intentional or unknown → follow the standard HookSentError runbook above (DNS/SSL/timeout, logs, monitoring, batch recovery).

• Always use HTTPS for your webhook endpoint
• Implement idempotent processing: in rare cases the PSB may deliver an event more than once
• Return a 2xx status code quickly: the PSB treats any non-2xx response as an error and will retry the event
• Log all received events for debugging and auditing
• Use a queue on your side if processing takes time; confirm receipt first and process afterwards

Prefer to retrieve documents in bulk? Check out the batch hook.