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

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

Event types

Event	Description
`validation.completed`	A single async validation finished successfully
`validation.failed`	A single async validation failed (upstream unavailable with no cached result)
`batch.completed`	All items in an async batch have been processed
`test`	Sent 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",
    "source": "vies",
    "source_status": "live",
    "cached": false,
    "stale": false
  },
  "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 member state DE is currently unavailable",
    "vat_number": "DE123456789"
  },
  "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": {
          "source": "vies",
          "source_status": "live",
          "cached": false,
          "stale": false
        }
      },
      {
        "error": {
          "code": "upstream_unavailable",
          "message": "VIES service unavailable",
          "vat_number": "IT12345678901"
        },
        "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}`;
}

import hmac
import hashlib
import time

def verify_webhook(body: str, signature: str, timestamp: str, secret: str) -> bool:
    age = int(time.time()) - int(timestamp)
    if age > 300:
        return False

    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.{body}".encode(),
        hashlib.sha256
    ).hexdigest()

    return signature == f"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 is handled separately. Queue delivery to the background worker is retried up to 5 times with exponential backoff. If an upstream registry is down, the worker consults the national tax register where one exists (unless the request was submitted with fallback: false) and serves its answer when it confirms the number (meta.source_status: "fallback"), then the most recent stored result where one exists (meta.source_status: "unavailable"); otherwise it marks the validation as failed, sends a validation.failed webhook, and refunds the validation to your quota. Webhook delivery and validation processing 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.

Getting Started

Core Concepts

Guides

Errors

Webhooks

Webhooks

Setup

Event types

Event payloads

validation.completed

validation.failed

batch.completed

test

Verifying signatures

Retry behavior

Best practices

​Webhooks

​Setup

​Event types

​Event payloads

​validation.completed

​validation.failed

​batch.completed

​test

​Verifying signatures

​Retry behavior

​Best practices

Webhooks

Setup

Event types

Event payloads

validation.completed

validation.failed

batch.completed

test

Verifying signatures

Retry behavior

Best practices