ATverify
API referenceWebhooks

Register a webhook endpoint

Registers an HTTPS URL to receive signed webhook events. The `secret` is returned once — store it securely. Requires Pro or Business plan.

Try it live
playground
Body

30 requests per hour per IP · demo key used automatically

Auth
Requires the Authorization: Bearer <api_key> header. Use a vtv_live_* key in production or a vtv_test_* key for deterministic magic-number responses.

Body

urlrequiredstring
example https://example.com/webhooks/vatverify
201

Response

Webhook endpoint registered

idrequiredstring
example 019d917e-4fa4-766e-9e0f-d977b47bf2c6
urlrequiredstring
example https://example.com/webhooks/vatverify
secretrequiredstring

Shown once — store it securely.

example whsec_a1b2c3d4e5f6...
labelrequiredstring | null
enabledrequiredboolean
last_delivery_atrequiredstring | null
last_delivery_statusrequiredinteger | null
created_atrequiredstring
example 2026-04-15T10:00:00Z

Error responses

400Invalid URL or webhook limit reached
401Missing or invalid API key
402Plan does not include webhooks — Pro or Business required
import { Vatverify } from '@vatverify/node';
const client = new Vatverify();

const result = await client.createWebhook({
    "url": "https://example.com/webhooks/vatverify"
  });
{
  "id": "019d917e-4fa4-766e-9e0f-d977b47bf2c6",
  "url": "https://example.com/webhooks/vatverify",
  "secret": "whsec_a1b2c3d4e5f6...",
  "label": "…",
  "enabled": true,
  "last_delivery_at": "…",
  "last_delivery_status": 0,
  "created_at": "2026-04-15T10:00:00Z"
}

Validate a VAT number

Validate a VAT number against the appropriate upstream service (VIES, HMRC, BFS, or BRREG) and return the validity status, company details, and VAT metadata for the country. Input is normalized automatically — spaces, dots, and casing are handled for you ("de 811.569.869" → "DE811569869"). Results are cached for 30 days. Cached responses include `meta.cached: true`; `data.verified_at` always reflects the original registry fetch time. Pass `cache=false` to bypass the cache and force a fresh lookup from the upstream service.

Delete a webhook endpoint

Next Page