When a recipient reports the status of your invoice via an Invoice Response (status message), the PSB sends a notification to your webhook. This way, as a sender, you know whether an invoice has been approved, rejected, or whether the recipient needs additional information. This article describes how to receive and process those notifications.

After sending an invoice, the recipient can send status messages back via the Peppol network. The PSB automatically links each incoming Invoice Response to your original invoice and publishes a webhook event.

The flow:

1. You send an invoice via the PSB
2. The recipient processes the invoice and sends an Invoice Response
3. The PSB receives the response message and links it to your invoice
4. Your webhook receives an InvoiceResponseReceived event

Register a hook on the InvoiceResponseReceived topic:

POST /api/v1/hook

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

The webhook payload contains the documentId of the original invoice and the responseDocumentId of the Invoice Response message.

Retrieve the full Invoice Response message via the API:

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

The message contains the status code, any clarification codes and an optional note from the recipient.

The received status code indicates what stage the invoice is at with the recipient:

For the UQ and RE statuses, it is important to read the Reason code and Action code that were sent along. These indicate what is wrong and what action the recipient expects from you. See the article Send an Invoice Response for a full overview of all Reason and Action codes.

To receive Invoice Responses as a sender, your organisation must be registered in the Peppol SMP with the invoiceResponse capability. Without this registration, the recipient's Access Point cannot deliver the response message.

Check and activate the capability:

PUT /api/v1/peppol/config HTTP/1.1
Host: psb.econnect.eu
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "invoiceResponse": {
    "state": "on"
  }
}

Some recommendations for processing Invoice Responses:

• Link to the invoice: use the documentId from the payload to link the response to the correct invoice in your own records.
• Display the status: make the invoice status visible to your users. An "approved" or "rejected" indicator prevents unnecessary follow-up queries.
• Respond to rejections: with status RE, it is common practice to correct the invoice and send a new version. Note: use a new X-EConnect-DocumentId for this, as it is a new document.
• Keep the audit trail: store every received Invoice Response as part of the invoice history.

Invoice Responses are optional in the Peppol network. Not every recipient sends them. But when they are used, they provide valuable insights into the invoicing process.

• Send an Invoice Response (status messages)
• Send an invoice via the API
• Receive an invoice via the API
• Configure and secure webhooks
• NLCIUS: the Dutch e-invoicing standard
• Invoice statuses on the platform