Webhook subscriptions

This endpoint allows you to create and manage webhook subscriptions for real-time notifications about only Peppol, Pagero and Weexa document processing events. Webhooks are HTTP POST requests sent to your specified endpoints when specific events occur during document processing.

Available Subscriptions

Subscription Type	Description
`invoice.receive`	Incoming invoice processed and ready for retrieval;
`invoice.exported`	Outgoing invoice successfully exported (without delivery confirmation)
`invoice.delivered`	Outgoing invoice successfully delivered
`invoice.error`	Document validation or participant lookup failed
`applicationresponse.receive`	Incoming application response processed and ready for retrieval
`applicationresponse.exported`	Outgoing application response successfully exported (without delivery confirmation)
`applicationresponse.delivered`	Outgoing application response successfully delivered
`applicationresponse.error`	Sending of application response failed
`ereport.exported`	E-report document successfully exported (without delivery confirmation)
`ereport.delivered`	E-report document successfully delivered
`ereport.error`	Sending of e-report document failed

For the events per subscription:

Webhook events

Authentication & Security

All webhook requests include HMAC SHA256 signatures for verification:

X-Timestamp: Unix timestamp when the webhook was sent
X-Signature: HMAC SHA256 signature in the format sha256={signature}

Webhook security

Important Notes

Endpoint Usage

PUT /v3/webhook: Use for initial webhook setup and future updates. This will create a new subscription or update an existing one.
GET /v3/webhook: Retrieve your current webhook subscriptions and get the webhook id needed for deletion.
DELETE /v3/webhook/{id}: Remove a specific webhook subscription using the id from the PUT or GET response.

Security & Performance

Your webhook endpoint must be accessible via HTTPS
Webhooks have a 30-second timeout - ensure quick responses
Webhook delivery failures are automatically retried using exponential backoff for up to 24 hours.
Use the provided signingSecret to verify webhook authenticity
Pre-signed download URLs in webhook payloads expire after 10 minutes

Create/Update webhook subscription

Endpoint

Method: PUT
Path: /v3/webhook

Full URLs

Test: https://apitest.4exchange.app/v3/webhook
Production: https://api.4exchange.app/v3/webhook

Request

Headers

Authorization: Bearer token (requires 4Exchange/webhook scope)
Content-Type: application/json

Request Body

{
    "endpoint": "https://your-webhook-endpoint.com/webhook",
    "subscriptions": [
        "invoice.receive",
        "invoice.delivered", 
        "invoice.error"
    ]
}

Example: Registering Multiple Endpoints

You can create multiple subscriptions by sending separate requests, each with a different endpoint:

{
    "endpoint": "https://your-webhook-endpoint.com/invoice-receive",
    "subscriptions": ["invoice.receive"]
}

{
    "endpoint": "https://your-webhook-endpoint.com/invoice-error",
    "subscriptions": ["invoice.error"]
}

Field Descriptions

Field	Type	Required	Description
`endpoint`	string	Yes	Your HTTPS webhook endpoint URL
`subscriptions`	array	Yes	Array of subscription types you want to receive

Responses

200 OK

200 OK

{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "endpoint": "https://your-webhook-endpoint.com/webhook",
    "subscriptions": [
        "invoice.receive",
        "invoice.delivered",
        "invoice.error"
    ],
    "signingSecret": "wh_secret_1234567890abcdef"
}

400 Bad Request

400 Bad Request

{
    "message": "Invalid request body"
}

401 Unauthorized

401 Unauthorized

{
    "message": "Unauthorized"
}

Get webhook subscriptions

Endpoint

Method: GET
Path: /v3/webhook

Full URLs

Test: https://apitest.4exchange.app/v3/webhook
Production: https://api.4exchange.app/v3/webhook

Request

Headers

Authorization: Bearer token (requires 4Exchange/webhook scope)

Responses

200 OK

200 OK

{
    "webhooks": [
        {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "endpoint": "https://your-webhook-endpoint.com/webhook",
            "subscriptions": [
                "invoice.error",
                "invoice.receive"
            ]
        }
    ]
}

401 Unauthorized

401 Unauthorized

{
    "message": "Unauthorized"
}

Rotate webhook signing secret

The new signingSecret is returned only once in the rotate response. It is never retrievable again by any API, store it securely immediately after rotation.

Endpoint

Method: POST
Path: /v3/webhook/rotate-secret

Request

Headers

Authorization: Bearer token (requires 4Exchange/webhook scope)

Responses

200 OK

200 OK

{
    "signingSecret": "wh_secret_1234567890abcdef"
}

401 Unauthorized

401 Unauthorized

{
    "message": "Unauthorized"
}

Delete webhook subscription

Endpoint

Method: DELETE
Path: /v3/webhook/{id}

Request

Headers

Authorization: Bearer token (requires 4Exchange/webhook scope)

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The webhook subscription ID (obtained from PUT or GET /v3/webhook)

Responses

200 OK

200 OK

{
    "message": "Webhook subscriptions successfully deleted: 123e4567-e89b-12d3-a456-426614174000"
}

401 Unauthorized

401 Unauthorized

{
    "message": "Unauthorized"
}

404 Not Found

404 Not Found

{
    "message": "Webhook subscription not found"
}