https://api.eurodebt.eu/api/{version}

1. Obtain an API key from your Eurodebt dashboard. Navigate to Management > Settings > API Keys and click on "Create API Key".
2. Include the API key in all requests via the x-api-key header
3. Submit verification requests and receive results via webhooks or polling

All API requests require authentication using an API key. Include your API key in the x-api-key header.

x-api-key: your-api-key-here

API keys have permissions that control access to different endpoints:

• read: Access to retrieve verification requests, reports, and usage data
• write: Ability to submit new verification requests

The API is rate-limited to 100 requests per minute per API key When rate limited, you will receive a 429 Too Many Requests response.

Rate limit headers are included in all responses:

• RateLimit-Limit: Maximum requests per window
• RateLimit-Remaining: Remaining requests in current window
• RateLimit-Reset: Time when the rate limit resets (Unix timestamp)

Webhooks allow you to receive real-time notifications when events occur in your account. Instead of polling the API for updates, you provide a URL and Eurodebt will send HTTP POST requests to that URL when relevant events happen.

How Webhooks Work

1. Configure: Provide a webhookUrl when submitting a request (e.g., verification request, PDF generation)
2. Event occurs: When the operation completes or fails, Eurodebt sends a POST request to your URL
3. Process: Your server receives the payload, verifies the signature, and processes the data
4. Acknowledge: Return a 2xx status code within 10 seconds to confirm receipt

Webhook Security (Signature Verification)

All webhook requests are signed using HMAC-SHA256 with your API key's webhook secret. The signature is included in the X-Eurodebt-Signature header.

Header format: sha256=<hex-encoded-signature>

Node.js / Express:

const crypto = require('crypto');

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-eurodebt-signature'];
  
  const expected = 'sha256=' + crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).send('Invalid signature');
  }

  res.status(200).send('OK');
});

Python / Flask:

import hmac, hashlib

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Eurodebt-Signature', '')
    expected = 'sha256=' + hmac.new(WEBHOOK_SECRET.encode(), request.data, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(signature, expected):
        return 'Invalid signature', 401

    return 'OK', 200

PHP:

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_EURODEBT_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $payload, WEBHOOK_SECRET);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

http_response_code(200);

Webhook Headers

Each webhook request includes the following headers:

Webhook Retry Policy

If webhook delivery fails, the system implements an automatic retry mechanism:

1. Immediate retries: Up to 3 attempts with delays of 1s, 5s, and 30s
2. Scheduled retries: If immediate retries fail, the webhook is scheduled for background retries at increasing intervals:
   • 5 minutes, 15 minutes, 30 minutes, 1 hour, 2 hours, 4 hours, 8 hours
3. Maximum retries: After 10 total attempts, the webhook is marked as failed

Retryable errors:

• Network timeouts and connection errors
• HTTP 5xx server errors

Non-retryable errors (no further attempts):

• HTTP 4xx client errors (except 429)

Webhook Delivery Status

You can check webhook delivery status by retrieving the verification request:

Important Notes

• Respond quickly: Return a 2xx status within 10 seconds to acknowledge receipt
• Verify signatures: Always validate the X-Eurodebt-Signature header

1. Submit request → POST /verification/submit returns requestId
2. Processing → Verification is processed
3. Completion → Webhook is sent (if configured) with status: "completed" or status: "rejected"
4. Retrieve report → Use verificationId from webhook or poll GET /verification/request/{id}

Several endpoints support a language parameter for translatable fields.

All errors return a consistent JSON structure:

{
  "error": {
    "type": "ERROR_TYPE",
    "message": "Human-readable error description"
  }
}

Endpoints for submitting and retrieving verification requests and reports

Endpoints for monitoring account usage and quotas

Webhook callbacks sent by Eurodebt when operations complete. Each webhook type has its own payload structure documented below.