Webhooks

Qvalia delivers platform events to your server through HTTPS POST requests.

Partners can configure webhooks for their own accounts. They can also configure child accounts using /partner/{partnerRegNo}/account/{accountRegNo}/webhook/... which scopes the subscription to a single account.

A partner can thus have a single webhook subscription on their Partner account, or multiple per child accounts.

The first PUT creates it and returns a generated webhook id (a UUID v4); subsequent PUT requests update the same subscription (its url and/or types). Use the returned id with the /partner/{partnerRegNo}/webhook/{webhookId}/auth endpoints to attach outbound authentication.

Event types

• new_document — sent when a new inbound document is received or created for an account.

• document_delivery — sent when an outbound document's delivery status changes.

• document_error — sent when a document's delivery fails, or an error occurs during processing.

Scope

This subscription receives events for every account your partner account can receive. Use /partner/{partnerRegNo}/account/{accountRegNo}/webhook/configure to scope the subscription to a single account.

Delivery (webhook usage)

Events are delivered as HTTP POST requests with JSON bodies to the configured url.

The URL must use https!

Your endpoint should respond with a 2xx status code.

Delivery requests time out after 10 seconds.

Delivery is at-least-once: on an internal retry (or if the same document is published by more than one upstream producer) you may occasionally receive the same event more than once. Design your endpoint to be idempotent. Deliveries for the same underlying event are identical except for status.updatedAt, so dedupe on the combination of eventType + globalTransactionId + status.status.

If configured, outbound authentication is applied as request headers or token body on every delivery. See /partner/{partnerRegNo}/webhook/{webhookId}/auth.

Each delivery is a single flat JSON object — the top-level event fields (eventType, accountRegNo, documentType, direction, integrationId, occurredAt) plus document-specific detail (documentId, globalTransactionId, status, error, peppol_metadata) on the same level.

status.event reflects the internal event that triggered the webhook and is always one of message-log/create / message-log/update / message-log/error — a 1:1 mapping onto the top-level eventType. status.status, by contrast, is a free-text delivery status reported by the upstream delivery channel (Peppol, email, print, …) and is not a fixed enum and may change.

Delivered payload

Each delivery is a JSON object. Samples provided below:

new_document:

{
  "eventType": "new_document",
  "accountRegNo": "SE5560004755",
  "documentType": "Invoice",
  "direction": "outgoing",
  "integrationId": "6b928ef1-fb0d-4b9a-a56f-b5dbca7a0fd4",
  "occurredAt": "2026-08-19T09:25:36.512Z",
  "documentId": "123456-INV",
  "globalTransactionId": "6b928ef1-fb0d-4b9a-a56f-b5dbca7a0fd4",
  "status": {
    "event": "message-log/create",
    "deliveryMethod": "peppol",
    "updatedAt": "2026-08-19T09:25:37.228Z"
  },
  "peppol_metadata": {
    "messageId": "9cab8ba5-d2a4-45d0-842d-8ede91dcac9f@QVALIA-PSE000094",
    "accessPoint": "PSE000094",
    "docTypeId": "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",
    "processId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
    "exchangeDateTime": "2026-08-19T09:25:34.226Z"
  }
}

document_delivery — a status transition on a document already announced via new_document; documentId is often absent at this stage:

{
  "eventType": "document_delivery",
  "accountRegNo": "SE5560004755",
  "documentType": "Invoice",
  "direction": "outgoing",
  "integrationId": "6b928ef1-fb0d-4b9a-a56f-b5dbca7a0fd4",
  "occurredAt": "2026-08-19T09:26:10.104Z",
  "globalTransactionId": "6b928ef1-fb0d-4b9a-a56f-b5dbca7a0fd4",
  "status": {
    "status": "processed",
    "event": "message-log/update",
    "deliveryMethod": "peppol",
    "updatedAt": "2026-08-19T09:26:09.881Z"
  },
  "peppol_metadata": {
    "messageId": "9cab8ba5-d2a4-45d0-842d-8ede91dcac9f@QVALIA-PSE000094",
    "accessPoint": "PSE000094",
    "docTypeId": "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",
    "processId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
    "exchangeDateTime": "2026-08-19T09:25:34.226Z"
  }
}

---

ERROR events may be recoverable!

Depending on your account configuration, Peppol or another document retry mechanism may deliver the document after an error event.

An error event is triggered on the first error occurrence. In a delivery retry scheme, the document may be delivered later. You then receive a document_delivery event for the same transaction.

Do not retry a delivery error until the retry period is exhausted (24 hours by default).

document_error — delivery failed; error carries a human-readable reason:

{
  "eventType": "document_error",
  "accountRegNo": "SE5560004755",
  "documentType": "Invoice",
  "direction": "outgoing",
  "integrationId": "6b928ef1-fb0d-4b9a-a56f-b5dbca7a0fd4",
  "occurredAt": "2026-08-19T09:26:10.104Z",
  "globalTransactionId": "6b928ef1-fb0d-4b9a-a56f-b5dbca7a0fd4",
  "status": {
    "status": "error",
    "event": "message-log/error",
    "deliveryMethod": "peppol",
    "updatedAt": "2026-08-19T09:26:09.881Z"
  },
  "error": "Peppol validation failed: invoice does not conform to UBL 2.1",
  "peppol_metadata": null
}