Webhooks - e-invoice.be

Webhooks allow you to receive real-time notifications about events in your e-invoice.be account. This guide explains how to set up and use webhooks effectively.

Overview

Webhooks are HTTP callbacks that notify your application when specific events occur, such as:

Document received
Document sent
Document send failed
Document receive failed

Setting Up Webhooks

1. Create a Webhook

curl -X POST "https://api.e-invoice.be/api/webhooks" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "url": "https://your-domain.com/webhook",
       "events": ["document.received", "document.sent", "document.sent.failed"],
       "enabled": true
     }'

2. Configure Your Endpoint

Your webhook endpoint should:

Accept POST requests
Use HTTPS with a valid SSL/TLS certificate (recommended; self-signed certificates are not supported)
Support HTTP Basic Authentication via URL format: https://username:password@host.com/endpoint (optional)
Return a 200 OK response quickly
Handle retries gracefully
Verify webhook signatures

Endpoint URL Requirements:

Protocol: HTTP and HTTPS are both supported (HTTPS strongly recommended for production)
Certificate: If using HTTPS, SSL/TLS certificate must be valid and issued by a trusted Certificate Authority
Self-signed certificates: Not supported - webhook delivery will fail with HTTPS
Redirects: Not followed. The configured URL must be the final endpoint - any 3xx redirect response (301, 302, 307, 308, etc.) is treated as a delivery failure and will be retried. This is a deliberate security measure to prevent SSRF and redirect-based attacks.

Authentication: You can include HTTP Basic Authentication credentials directly in the URL:

https://username:password@your-domain.com/webhook
http://username:password@your-domain.com/webhook

URL format: Standard URL format with optional path, query parameters, and authentication

Configure your webhook URL to point directly at the final endpoint. If your URL responds with a redirect (e.g., http:// → https://, or apex → www), delivery will fail. Update the registered webhook URL to match the destination your server actually serves the handler from.

Webhook Security

Signature Verification

Webhook requests are signed using HMAC-SHA256 to ensure authenticity and integrity. The signature is included in the X-Signature header of each request.

How the Signature is Computed

The signature is computed over the entire webhook event payload (not just the data field). This ensures the integrity of all webhook data including the event ID, timestamp, type, and content.

The complete webhook event is serialized to JSON with sorted keys
The JSON string is encoded to UTF-8 bytes
An HMAC is created using your webhook secret and the SHA-256 algorithm
The resulting signature is formatted as sha256={hexadecimal_signature}

Example

Given this complete webhook event payload:

{
  "id": "evt-e7wyc7gtpqx4z73x2wqmwhebhbb3r8n3ovfhcsdbulxr3s2awf49de76yglrnri3",
  "tenant_id": "ten-abc123",
  "created_at": 1762780249,
  "type": "document.sent",
  "data": {
    "document": {
      "id": "doc-1",
      "name": "test.xml",
      "type": "application/xml",
      "size": 100,
      "url": "https://example.com/test.xml"
    }
  },
  "text": "⚡️ New webhook event: document.sent\n\n{\n  \"document_id\": \"doc-1\"\n}"
}

When serialized to JSON with sorted keys, this becomes the following string (before UTF-8 encoding):

{"created_at": 1762780249, "data": {"document": {"id": "doc-1", "name": "test.xml", "size": 100, "type": "application/xml", "url": "https://example.com/test.xml"}}, "id": "evt-e7wyc7gtpqx4z73x2wqmwhebhbb3r8n3ovfhcsdbulxr3s2awf49de76yglrnri3", "tenant_id": "ten-abc123", "text": "\u26a1\ufe0f New webhook event: document.sent\n\n{\n  \"document_id\": \"doc-1\"\n}", "type": "document.sent"}

Important: Notice how special characters are properly escaped in the JSON serialization:

Newlines are represented as \n (literal backslash-n, not actual line breaks)
Unicode characters like emojis are escaped as \u26a1\ufe0f (for ⚡️)
Quotes inside the text field are escaped as \"

This is critical for signature verification. The JSON must be serialized with:

Sorted keys (sort_keys=True in Python’s json.dumps())
No extra whitespace (compact format, not pretty-printed)
Proper escaping of special characters (standard JSON encoding)

Your JSON library should handle this automatically when using json.dumps(payload, sort_keys=True) in Python, JSON.stringify() in JavaScript, or equivalent functions in other languages. With the webhook secret "secret", this produces the signature:

sha256=019f1175f2232f456ff4ebcc396432f8b0f5168d62446f95d1c0217e2ca2fa4d

Computing the Signature

All webhook requests from e-invoice.be include a cryptographic signature that allows you to verify the request’s authenticity. This prevents unauthorized parties from sending fake webhook events to your endpoint. Here’s the exact code used by e-invoice.be to compute webhook signatures:

import hmac
import hashlib
import json

def compute_signature(webhook_event_json: str, secret: str) -> str:
    """
    Compute HMAC-SHA256 signature for the entire webhook event payload.

    Args:
        webhook_event_json: JSON string of the complete webhook event
                           (serialized with sort_keys=True, exclude_none=True)
        secret: Your webhook secret

    Returns:
        Signature in format "sha256={hex_digest}"
    """
    payload_bytes = webhook_event_json.encode("utf-8")
    signature = hmac.new(
        secret.encode("utf-8"), payload_bytes, hashlib.sha256
    ).hexdigest()
    return f"sha256={signature}"

How it works:

Serialize the entire webhook event: The complete webhook event (including id, tenant_id, created_at, type, data, and text fields) is serialized to JSON with sort_keys=True to ensure consistent key ordering. This is critical because {"a": 1, "b": 2} and {"b": 2, "a": 1} are semantically identical but would produce different signatures without key sorting.
Convert to bytes: The JSON string is encoded to UTF-8 bytes, which is required for the HMAC operation.
Generate HMAC: Using your webhook secret as the key, an HMAC (Hash-based Message Authentication Code) is computed using the SHA-256 hashing algorithm. This creates a cryptographic signature that only someone with your secret can reproduce.
Format the result: The hexadecimal digest is prefixed with sha256= to indicate the algorithm used, matching the format in the X-Signature header.

Why HMAC? HMAC is preferred over simple hashing because it requires a secret key. Even if an attacker knows the payload and hashing algorithm, they cannot generate a valid signature without your webhook secret. Important: The signature covers the entire webhook event payload you receive in the POST request body, not just the data field. This ensures the integrity and authenticity of all event information including the event ID, timestamp, type, and all data.

Verifying the Signature

To verify the signature in your webhook handler:

Extract the signature from the X-Signature header (format: sha256={hex_digest})
Parse the request body as JSON, then re-serialize it with sorted keys and no extra whitespace (e.g. json.dumps(payload, sort_keys=True) in Python, or the equivalent in your language)
Encode that canonical JSON string to UTF-8 bytes
Compute the HMAC-SHA256 over those bytes using your webhook secret
Compare the computed signature with the one in the header using a constant-time comparison

The signature is computed over the JSON serialized with sort_keys=True, but the body delivered over the wire is not guaranteed to use that same key order. You must parse the JSON and re-serialize it with sorted keys before computing the HMAC — verifying directly against the raw request body will fail whenever the transport-level key order differs from the canonical (sorted) order.

Important Notes:

Always verify the signature before processing the webhook
Use constant-time comparison to prevent timing attacks
The signature covers the entire webhook event (all fields: id, tenant_id, created_at, type, data, text) — not just the data field
Re-serialize with sort_keys=True and no extra whitespace; do not pretty-print
If the signatures match, the webhook request is authentic and hasn’t been tampered with

Available Events

The following webhook events are supported:

document.received: A new document is successfully received via Peppol or other channels
document.received.failed: A document failed to be received/processed
document.sent: A document is successfully sent via Peppol or other channels
document.sent.failed: A document failed to send (e.g., validation error, network error, Peppol transmission failure)

Webhook Payload

When a webhook is triggered, it sends a POST request to your configured URL with the following structure:

{
  "id": "evt_3k8d9f2h4j6m8n0p",
  "tenant_id": "ten_5x7y9z1a3b5c7d9e",
  "created_at": 1729468923,
  "type": "document.sent",
  "data": {
    "document_id": "doc_2f4h6j8k0m2n4p6q"
  },
  "text": "⚡️ New webhook event: document.sent\n\n{\n  \"document_id\": \"doc_2f4h6j8k0m2n4p6q\"\n}"
}

Note: Currently, the data object only contains the document_id. You can use this ID to fetch additional document details via the API (GET /api/documents/{document_id}).

Headers

Each webhook request includes the following headers:

X-Signature: HMAC-SHA256 signature for verifying authenticity (format: sha256=...)
X-Event-Type: The event type (e.g., document.sent)
Content-Type: application/json
User-Agent: e-invoice-be-webhook-service

Event Data Structure

The data object contains event-specific information:

For all document events (document.received, document.sent, document.sent.failed, document.received.failed):
```
{
  "document_id": "doc_2f4h6j8k0m2n4p6q"
}
```

The document_id can be used to retrieve full document details:

curl -X GET "https://api.e-invoice.be/api/documents/{document_id}" \
     -H "Authorization: Bearer YOUR_API_KEY"

Complete Example Requests

Success Event Example

Here’s what a successful document.sent webhook HTTP request looks like:

POST /webhook HTTP/1.1
Host: your-domain.com
Content-Type: application/json
User-Agent: e-invoice-be-webhook-service
X-Signature: sha256=a3f8d9e2c1b5a7f9e3d2c1b5a7f9e3d2c1b5a7f9e3d2c1b5a7f9e3d2c1b5
X-Event-Type: document.sent

{
  "id": "evt_3k8d9f2h4j6m8n0p",
  "tenant_id": "ten_5x7y9z1a3b5c7d9e",
  "created_at": 1729468923,
  "type": "document.sent",
  "data": {
    "document_id": "doc_2f4h6j8k0m2n4p6q"
  },
  "text": "⚡️ New webhook event: document.sent\n\n{\n  \"document_id\": \"doc_2f4h6j8k0m2n4p6q\"\n}"
}

Failure Event Example

Here’s what a failed document.sent.failed webhook HTTP request looks like:

POST /webhook HTTP/1.1
Host: your-domain.com
Content-Type: application/json
User-Agent: e-invoice-be-webhook-service
X-Signature: sha256=7e9c3a1d5f8b2e6a4c9d7f3b1e8a6c2d9f7e3a1c5b8d6f2a4e9c7b3d1f8a5c
X-Event-Type: document.sent.failed

{
  "id": "evt_9m2p4r6t8v0x2z4b",
  "tenant_id": "ten_5x7y9z1a3b5c7d9e",
  "created_at": 1729469845,
  "type": "document.sent.failed",
  "data": {
    "document_id": "doc_8h3j5k7m9n1p3q5r"
  },
  "text": "⚡️ New webhook event: document.sent.failed\n\n{\n  \"document_id\": \"doc_8h3j5k7m9n1p3q5r\"\n}"
}

Note: For failure events, you’ll need to retrieve the document details via the API to understand what went wrong. The document state will typically be set to FAILED and may contain error information. You can retry sending a failed document by calling POST /api/documents/{document_id}/send again.

Webhook Management

List Webhooks

curl -X GET "https://api.e-invoice.be/api/webhooks" \
     -H "Authorization: Bearer YOUR_API_KEY"

Update Webhook

curl -X PUT "https://api.e-invoice.be/api/webhooks/{webhook_id}" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "enabled": false
     }'

Delete Webhook

curl -X DELETE "https://api.e-invoice.be/api/webhooks/{webhook_id}" \
     -H "Authorization: Bearer YOUR_API_KEY"

Test Webhook

Send a test event to verify your webhook is working correctly:

curl -X POST "https://api.e-invoice.be/api/webhooks/{webhook_id}/test" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "event_type": "document.sent",
       "data": {
         "document_id": "test_doc_123"
       }
     }'

​Overview

​Setting Up Webhooks

​1. Create a Webhook

​2. Configure Your Endpoint

​Webhook Security

​Signature Verification

​How the Signature is Computed

​Example

​Computing the Signature

​Verifying the Signature

​Available Events

​Webhook Payload

​Headers

​Event Data Structure

​Complete Example Requests

​Success Event Example

​Failure Event Example

​Webhook Management

​List Webhooks

​Update Webhook

​Delete Webhook

​Test Webhook

Overview

Setting Up Webhooks

1. Create a Webhook

2. Configure Your Endpoint

Webhook Security

Signature Verification

How the Signature is Computed

Example

Computing the Signature

Verifying the Signature

Available Events

Webhook Payload

Headers

Event Data Structure

Complete Example Requests

Success Event Example

Failure Event Example

Webhook Management

List Webhooks

Update Webhook

Delete Webhook

Test Webhook