Docs
Integration Guides
Webhooks

Webhooks

Webhooks

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 failed
  • Document status changes

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"],
       "enabled": true
     }'

2. Configure Your Endpoint

Your webhook endpoint should:

  • Accept POST requests
  • Return a 200 OK response quickly
  • Handle retries gracefully
  • Verify webhook signatures

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

  1. The payload is sorted by keys and converted to a JSON string
  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 webhook payload:

{
  "document": {
    "id": "doc-1",
    "name": "test.xml",
    "type": "application/xml",
    "size": 100,
    "url": "https://example.com/test.xml"
  }
}

This translates to the string:

{"document": {"id": "doc-1", "name": "test.xml", "size": 100, "type": "application/xml", "url": "https://example.com/test.xml"}}

With the webhook secret of "secret", the signature would be:

sha256=6722b498bf28ce7ca5a6f21c0fca9166e24dea480978b276725ff46e503dd70f

Verifying the Signature

To verify the signature in your webhook handler:

  1. Extract the signature from the X-Signature header
  2. Compute the HMAC-SHA256 of the request body using your webhook secret
  3. Compare the computed signature with the one in the header

If the signatures match, the webhook request is authentic and hasn’t been tampered with.

Best Practices

  1. Handle Retries

    • Webhooks may be retried if your endpoint doesn’t respond
    • Implement idempotency to handle duplicate events
    • Return 200 OK quickly, process asynchronously

  2. Security

    • Always verify webhook signatures
    • Use HTTPS for your webhook endpoint
    • Keep your webhook secret secure

  3. Error Handling

    • Log failed webhook deliveries
    • Monitor webhook success rates
    • Set up alerts for repeated failures

  4. Testing

    • Use the webhook testing tool in the dashboard
    • Test with different event types
    • Verify signature verification

Available Events

  • document.created: A new document is created
  • document.sent: A document is successfully sent
  • document.received: A new document is received
  • document.failed: A document fails to send
  • document.updated: A document is updated
  • document.deleted: A document is deleted

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"

Next Steps