Skip to main content
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:[email protected]/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
  • Authentication: You can include HTTP Basic Authentication credentials directly in the URL: 
    https://username:[email protected]/webhook
http://username:[email protected]/webhook
  • URL format: Standard URL format with optional path, query parameters, and authentication

​
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.
  1. The complete webhook event is serialized to JSON with sorted keys
  2. The JSON string is encoded to UTF-8 bytes
  3. An HMAC is created using your webhook secret and the SHA-256 algorithm
  4. 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:
  1. 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.
  2. Convert to bytes: The JSON string is encoded to UTF-8 bytes, which is required for the HMAC operation.
  3. 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.
  4. 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:
  1. Extract the signature from the X-Signature header (format: sha256={hex_digest})
  2. Read the raw request body as a string (the complete JSON webhook event)
  3. Compute the HMAC-SHA256 signature using your webhook secret and the raw request body
  4. Compare the computed signature with the one in the header using a constant-time comparison
Important Notes:
  • Always verify the signature before processing the webhook
  • Use constant-time comparison to prevent timing attacks
  • The signature covers the entire raw request body (all fields: id, tenant_id, created_at, type, data, text)
  • Do not parse the JSON and re-serialize it - use the exact raw request body as received
  • 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"
       }
     }'