Skip to main content

​
Webhooks

Webhooks let you receive validation results asynchronously. Instead of blocking your application on a VIES, HMRC, or BFS lookup, submit the request and get the result delivered to your endpoint when it is ready. Available on Pro and Business plans. Avatcado signs every webhook delivery with HMAC-SHA256 so you can verify it came from Avatcado.

​
Setup

  1. Configure your webhook URL in the dashboard or via the API (PUT /v1/webhooks/config)
  2. Your endpoint must accept HTTPS POST requests
  3. Your endpoint should return 2xx within 10 seconds
  4. Avatcado logs every delivery attempt. You can view delivery history and replay failed deliveries from the dashboard.

​
Event types

EventDescription
validation.completedA single async validation finished successfully
validation.failedA single async validation failed after all retry attempts
batch.completedAll items in an async batch have been processed
testSent when you click “Send test event” in the dashboard

​
Event payloads

​
validation.completed

{
  "event": "validation.completed",
  "data": {
    "valid": true,
    "vat_number": "DE123456789",
    "country_code": "DE",
    "company": {
      "name": "ACME GmbH",
      "address": "Berlin"
    },
    "consultation_number": null,
    "requested_at": "2026-03-30T12:00:00Z"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "cached": false,
    "source_status": "live"
  },
  "created_at": "2026-03-30T12:01:00Z"
}

​
validation.failed

{
  "event": "validation.failed",
  "data": {
    "vat_number": "DE123456789"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "error": {
    "code": "upstream_unavailable",
    "message": "VIES service unavailable after all retry attempts"
  },
  "created_at": "2026-03-30T12:01:00Z"
}

​
batch.completed

{
  "event": "batch.completed",
  "data": {
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "summary": {
      "total": 197,
      "succeeded": 190,
      "failed": 7
    },
    "results": [
      {
        "data": {
          "valid": true,
          "vat_number": "DE123456789",
          "country_code": "DE",
          "company": { "name": "ACME GmbH", "address": "Berlin" },
          "requested_at": "2026-03-30T12:00:00Z"
        },
        "meta": {
          "cached": false,
          "source_status": "live"
        }
      },
      {
        "error": {
          "code": "upstream_unavailable",
          "message": "VIES service unavailable"
        },
        "meta": { "vat_number": "IT12345678901" }
      }
    ]
  },
  "created_at": "2026-03-30T12:01:00Z"
}

​
test

{
  "event": "test",
  "data": {
    "message": "Webhook configuration is working correctly."
  },
  "created_at": "2026-03-30T12:00:00Z"
}

​
Verifying signatures

Every delivery includes these headers:
  • X-Avatcado-Signature: sha256=<hex digest>
  • X-Avatcado-Timestamp: Unix timestamp (seconds)
  • X-Avatcado-Event: event type
  • X-Avatcado-Delivery-Id: unique delivery identifier
During the brand transition we also send the legacy X-Vatly-* headers with identical values, so existing integrations keep working unchanged. The legacy headers are deprecated and will be removed after 2026-07-01. Move your verification to the X-Avatcado-* headers before then.
The signature is computed as HMAC-SHA256 of {timestamp}.{body} using your signing secret. Always verify signatures before processing webhooks. Check the timestamp is within 5 minutes to prevent replay attacks. 
import { createHmac } from 'crypto';

function verifyWebhook(
  body: string,
  signature: string,
  timestamp: string,
  secret: string
): boolean {
  // Prevent replay attacks
  const age = Math.floor(Date.now() / 1000) - parseInt(timestamp);
  if (age > 300) return false; // Reject if older than 5 minutes

  const expected = createHmac('sha256', secret)
    .update(`${timestamp}.${body}`)
    .digest('hex');

  return signature === `sha256=${expected}`;
}

​
Retry behavior

If your endpoint returns non-2xx or times out, the delivery is logged as failed. You can replay failed deliveries from the dashboard. The underlying async validation itself is retried separately. If VIES or another upstream service is down, Avatcado retries the validation up to 5 times over several hours before marking it as failed and sending a validation.failed webhook. Webhook delivery and validation retries are independent. A failed delivery does not trigger a re-validation.

​
Best practices

  • Return 2xx quickly. Do heavy processing in the background after acknowledging the webhook.
  • Verify signatures on every request. Never trust unverified payloads.
  • Handle duplicate deliveries gracefully. Replays send the same payload with a new delivery ID.
  • Store the X-Avatcado-Delivery-Id header for debugging and deduplication.