Webhook API

Webhook Notifications

As defined in this document, we immediately notify the partner systems over webhook notifications.

Event	Description
ACCOUNT_CREATED	A new account has been created.
ACCOUNT_DEACTIVATED	The account has been temporarily deactivated.
ACCOUNT_TERMINATED	The account has been terminated (cancelled), but not yet deactivated.
ACCOUNT_INVITATION_ACCEPTED	An account member has accepted the invitation.
ACCOUNT_MEMBER_ADDED	A new member has been added to the account.
ACCOUNT_MEMBER_REMOVED	A member has been removed from the account.
ACCOUNT_ADDRESS_CHANGED	The account's address has been updated.
ACCOUNT_MAIL_REDIRECTION_CHANGED	The mail forwarding settings have been updated.
ACCOUNT_LINKING_INITIATED	An app integration has been initiated for the account by an agent over API.
ACCOUNT_LINKING_CONFIRMED	The customer has confirmed the app integration.
ACCOUNT_LINKING_REJECTED	The customer has rejected the app integration.
ACCOUNT_LINKING_DEACTIVATED	An existing app integration has been temporarily deactivated.
ACCOUNT_LINKING_REACTIVATED	A previously deactivated app integration has been reactivated.
ACCOUNT_LINKING_TERMINATED	The app integration has been permanently terminated (cancelled).
NEW_DOCUMENT	A new document has been received and is available for retrieval.
NEW_XML_DOCUMENT	A new XML document has been generated and is available for retrieval. This event is specific to insurance brokers.
DOCUMENT_METADATA_CHANGED	The document metadata has been updated (either by a user or an automated job) and is available for retrieval.
DOCUMENT_CONTENT_CHANGED	The content (new annotations) of the document has been updated.
DOCUMENT_MOVED_TO_BIN	The document has been moved to the recycle bin (not permanently deleted).
DOCUMENT_RESTORED_FROM_BIN	The document has been restored from the recycle bin to its previous inbox.
DOCUMENT_PURGED	The document has been permanently deleted and is no longer accessible.
DOCUMENT_UNTRACKED	The document type has been changed. The new type is no longer relevant for the API.
INITIAL_TRANSMISSION_STARTED	For accounts with a start date in the past, data transmission started in batches.
INITIAL_TRANMISSION_ERRORED	An error occurred during the initial transmission process.
INITIAL_TRANMISSION_FINISHED	The initial transmission process was successfully completed.

Request

POST {PARTNER_WEBHOOK_URL}

{
  "type": ["ACCOUNT" | "DOCUMENT"],
  "event": [
    "ACCOUNT_CREATED",
    "ACCOUNT_DEACTIVATED",
    "ACCOUNT_TERMINATED",
    "ACCOUNT_INVITATION_ACCEPTED",
    "ACCOUNT_MEMBER_ADDED",
    "ACCOUNT_MEMBER_REMOVED",
    "ACCOUNT_ADDRESS_CHANGED",
    "ACCOUNT_MAIL_REDIRECTION_CHANGED",    
    "ACCOUNT_LINKING_INITIATED",
    "ACCOUNT_LINKING_CONFIRMED",
    "ACCOUNT_LINKING_REJECTED",
    "ACCOUNT_LINKING_DEACTIVATED",
    "ACCOUNT_LINKING_REACTIVATED",
    "ACCOUNT_LINKING_TERMINATED",
    "NEW_DOCUMENT",
    "NEW_XML_DOCUMENT",
    "DOCUMENT_METADATA_CHANGED",
    "DOCUMENT_CONTENT_CHANGED",
    "DOCUMENT_MOVED_TO_BIN",
    "DOCUMENT_RESTORED_FROM_BIN",
    "DOCUMENT_PURGED",
    "DOCUMENT_UNTRACKED",
    "INITIAL_TRANSMISSION_STARTED",
    "INITIAL_TRANMISSION_ERRORED",
    "INITIAL_TRANMISSION_FINISHED"
  ],
  "objectReferenceId": "UUID",
  "applicationClientReferenceId": "string",
  "account": "PEAXID",
  "occurredAt": "timestamp",
  "title": "string",
  "data": "string",
  "trackingId": "UUID"
}

Response

200 OK

If we do not get 200 and any error, then we retry it 10 times within the next 24h by applying an expenontial backoff algorithm.

💡

The webhook call has a timeout period of 180 seconds. If the process on the client side is not completed within this time, a new attempt is started.

PARTNER Webhook URL

This URL (PARTNER_WEBHOOK_URL) will be given to PEAX, and is configured in the environment by PEAX.

Object Reference Id

This is the internal PEAX UUID to the entity (document or account). This ID will be used for the subsequent requests.

Application Client Reference ID

This is the entity id of the user in the partner system.

Account ID

This is the PEAX ID of the business account. It is a string.

TrackingId

The initiator sets this id for tracing purposes.

Authentication

There are three mechanism to use for authentication of webhooks

NONE: No authentication is required

BASIC_AUTH: Basic authentication with a fixed username and password.

BEARER_TOKEN: Using oauth2.0 client credential flow. In this case, we expecting client_id, client_secret and the IDP token url from the partner.

curl --location '{PARTNER_WEBHOOK_URL}' \
--header 'Authorization: Basic {base64-encoded-username-password}' \
--header 'Content-Type: application/json' \
--data '{
  "type": "DOCUMENT",
  "event": "NEW_DOCUMENT",
  "objectReferenceId": "ef78ef59-f14b-429e-b131-1466bf2dad6e",
  "clientId": "PARTNER-CLIENT-1001001",
  "account": "999.9999.9999.99",
  "occurredAt": "2024-04-01T12:34:45.232",
  "title": "A title",
  "data": null,
  "trackingId": "UUID"
}'

Webhook Notifications#

Request#

Response#

PARTNER Webhook URL#

Object Reference Id#

Application Client Reference ID#

Account ID#

TrackingId#

Authentication#