Notifications

Overview

When a subscribed event occurs, the platform delivers an HTTP POST request to the notificationUrl configured in the webhook subscription. The request body contains a structured JSON payload describing the event.

Notifications are delivered asynchronously. Retry behavior is managed internally by the platform — retry policies do not need to be configured.

For information on how to register and manage webhook subscriptions, see the Webhook Subscription page.

Delivery

Each notification is delivered as an HTTP POST to the registered endpoint with the following characteristics:

Content-Type: application/json
The payload body contains a WebhookNotificationPayload object
The eventId field is a unique identifier for the notification and can be used for idempotent processing

If the endpoint returns a non-2xx response, the platform retries delivery automatically according to the configured retry strategy.

Event types

Event type	Description
`DOCUMENT_STATUS_CHANGED`	Triggered when the internal processing status of a document changes.
`INVOICE_STATUS_CHANGED`	Triggered when the external lifecycle status of an invoice changes.

Notification payload

The payload delivered to the registered endpoint on each notification.

Fields

Name	Type	Description
`eventId`	string	Unique identifier of this notification (UUID). Can be used to deduplicate deliveries.
`eventType`	string	Type of event that triggered this notification. See Event types.
`occurredAt`	string	ISO 8601 timestamp of when the status change occurred (e.g., `2025-03-30T10:15:00Z`).
`documentId`	string	Identifier of the document whose status changed.
`externalStatus`	string	External status of the document at the time of the event.
`currentStatus`	string	Current processing status of the document. See Document statuses.
`flowDetail`	string	Flow detail of the document (e.g., `VERIFACTU`). Provides additional context on the processing flow.

Document statuses

The currentStatus field reflects the document's internal processing status.

Status	Description
`CREATED`	The document has been received and registered in the platform.
`PROCESSING`	The document is being processed.
`OK`	The document has been successfully processed.
`ERROR`	The document failed during processing.
`DUPLICATED`	The document was identified as a duplicate and was not processed further.
`PENDING_ACTION`	The document is awaiting an action before processing can continue.

Example payload

{
  "eventId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "eventType": "DOCUMENT_STATUS_CHANGED",
  "occurredAt": "2025-03-30T10:15:00Z",
  "documentId": "INV-2025-00123",
  "externalStatus": "APPROVED",
  "currentStatus": "OK",
  "flowDetail": "VERIFACTU"
}

Idempotency

Each notification includes a unique eventId. If the same event is delivered more than once due to a retry, the eventId will be identical across deliveries. The eventId should be stored and checked to avoid processing the same event multiple times.