When an invoice for your organisation arrives via Peppol or another network, the PSB stores the document and sends a notification to your webhook. This article explains how to receive that notification, download the document and set up status management.

Receiving an invoice involves four steps:

1. Notification: the PSB sends an InvoiceReceived webhook event to your endpoint
2. Download: you retrieve the document via the PurchaseInvoice endpoint
3. Processing: you process the invoice in your own system
4. Cleanup (optional): you delete the document from the PSB

To receive invoices, you need a webhook listening on the InvoiceReceived topic. Register it via the Hook API:

POST /api/v1/hook

{
  "action": "https://mijn-systeem.nl/webhook/invoices#mijnSecretKey",
  "topics": ["InvoiceReceived"]
}

As soon as an invoice arrives, your endpoint receives a POST request with a JSON payload. This payload includes the documentId and the partyId you need to retrieve the document.

Tip: Also set up a webhook on the InvoiceReceivedError topic to receive notifications when something goes wrong during reception.

Use the documentId from the webhook payload to retrieve the invoice:

GET /api/v1/{partyId}/purchaseInvoice/{documentId}/download HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}

The response contains the XML document (by default in the original format). Want to receive the document in a different format? Use the targetDocumentTypeId parameter:

GET /api/v1/{partyId}/purchaseInvoice/{documentId}/download?targetDocumentTypeId={URN}

The PSB automatically transforms the document to the specified format before returning it.

The PSB retains received documents according to this schedule:

We recommend retrieving documents immediately after reception and storing them in your own system. Do not rely on the PSB for long-term storage.

After processing, you can manually delete the document:

DELETE /api/v1/{partyId}/purchaseInvoice/{documentId} HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}

This permanently deletes the document from the PSB. The audit trail remains available.

After reception, you can update the processing status of a purchase invoice. This is particularly relevant if you want to send Invoice Responses (status messages) to the sender. Read the article Send an Invoice Response for more information.

The PSB automatically sends an MLS message (Message Level Status) back to the sending party after receiving a document. This confirms that the document has been received and delivered. As an integrator you don't need to configure anything for this: the PSB handles this completely. If you send documents yourself, you receive MLS feedback via the webhook topic MessageLevelStatusReceived. See Configure webhooks for the configuration.

If you cannot configure webhooks (for example in an on-premise environment without inbound internet traffic), you can also retrieve invoices via polling:

GET /api/v1/{partyId}/purchaseInvoice HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}

This endpoint returns a list of available purchase invoices. However, webhooks are always the preferred method due to real-time processing and lower load on the API.

Note: For on-premise integrations, also consider the reverse webhook (HTTPS inbound hook), which allows the PSB to push documents without your system needing to be directly reachable from the internet.

• Process idempotently: in exceptional cases, the PSB may deliver an event multiple times. Check on your end whether you have already processed a document before importing it again.
• Download immediately: retrieve documents as soon as possible after the webhook notification. The 90-day retention is a safety net, not a storage strategy.
• Log the documentId: store the PSB documentId in your own system for tracing and potential troubleshooting.
• Convert formats: if you need a specific XML format, use targetDocumentTypeId when downloading rather than converting yourself.
• Webhook retries: if your endpoint is temporarily unreachable, the PSB retries delivery of the notification for up to 5 days. Extended downtime? Use batch hooks as a fallback to retrieve missed documents.

View the full PurchaseInvoice endpoints and response models at psb.econnect.eu.