Webhooks

Subscribe to signed event notifications for jobs, quota, and subscription changes — set up an endpoint, verify signatures, and handle retries.

Beliq posts a signed JSON payload to your endpoint when something happens on your account — an API job finishes, you approach a quota limit, or your subscription changes. Each delivery is an HTTP POST carrying an HMAC signature you verify with the endpoint’s secret.

Webhook endpoints are managed in the dashboard under Webhooks. To add one:

1. Enter the HTTPS URL that should receive deliveries.
2. Choose which events to subscribe to.
3. Beliq generates a signing secret (prefixed whsec_), shown once — copy it immediately and store it securely.

From the same page you can toggle an endpoint active or inactive, rotate its secret, and inspect the delivery log — every attempt, its status code, the response snippet, and any retries.

Endpoint URLs must be public https:// addresses. Private, loopback, and link-local targets are rejected, and the hostname is resolved at save time so a public name pointing at a private address is refused too.

Use the default port. Only ports 80 and 443 are accepted, and only 443 is actually reachable: our egress permits nothing else. An endpoint saved as https://example.com:80/hooks therefore saves cleanly and then fails every delivery until the retry schedule is exhausted. Leave the port off the URL.

Every delivery shares the same envelope. Only data changes by event type.

{
  "id": "evt_3f9a1c0b8d7e4f2a9b6c5d4e3f2a1b0c",
  "type": "job.completed",
  "created_at": "2026-06-21T10:21:58.000Z",
  "organization_id": "8b1d2c3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e",
  "livemode": true,
  "data": { }
}

Test mode and livemode

A sandbox key (blq_test_) records its call in your history and stops there: it produces no webhook at all. Every one of the ten job, quota and subscription events below is therefore emitted with livemode: true, and there is currently no “send test event” control in the dashboard. Handle the field, but do not wait for a false on these events, and do not use it as your live/test switch — it will not fire.

To exercise a handler end to end today, use a live key against the free monthly allowance:

• job.completed and job.validation_failed — send a document to /v1/validate. A deliberately invalid one produces both.
• quota.threshold_reached / quota.exceeded — only reachable by actually consuming the plan’s monthly documents.
• job.failed and the subscription.* events — cannot be triggered on demand. They mean a Beliq-side fault or a real billing transition.

The transmission events are the exception: they carry the transmission’s own mode, so a test-mode delivery does emit livemode: false.

Job data

{
  "job_id": "f2a1b0c9-d8e7-4f6a-5b4c-3d2e1f0a9b8c",
  "operation": "validate",
  "standard": "ubl",
  "profile": "xrechnung",
  "status": "completed",
  "input_format": "xml",
  "output_format": "json",
  "processing_ms": 142,
  "validation": {
    "valid": false,
    "error_count": 2,
    "warning_count": 1,
    "format": "ubl",
    "profile_detected": "xrechnung"
  }
}

Quota data

{
  "period_start": "2026-06-20T09:00:00.000Z",
  "period_end": "2026-07-20T09:00:00.000Z",
  "used": 8000,
  "limit": 10000,
  "threshold": 0.8
}

The quota window is one month wide and anchored on your billing day, so it is a calendar month only if your subscription renews on the 1st. An annual subscription still gets monthly windows: the allowance is per month, not a single yearly pool.

Subscription data

{
  "plan": "Growth",
  "interval": "annual",
  "period_start": "2026-06-01T00:00:00.000Z",
  "period_end": "2027-06-01T00:00:00.000Z",
  "currency": "EUR",
  "previous_plan": "Starter",
  "effective_at": "2026-06-21T10:21:58.000Z"
}

Subscribe to these to follow a delivery without polling. Each carries TransmissionData.

Transmission data

{
  "transmission_id": "txn_9f3c2a1b8e",
  "direction": "outbound",
  "network": "peppol",
  "status": "delivered",
  "at_risk": false,
  "counterparty": { "scheme": "0208", "id": "9876543210" },
  "deadline_at": "2026-04-20T00:00:00.000Z"
}

Each request carries an X-Beliq-Signature header with a Unix timestamp and an HMAC-SHA256 signature computed over <timestamp>.<body> using your endpoint’s secret:

X-Beliq-Signature: t=1700000000,v1=4f3c...

Verify by parsing the header, recomputing the HMAC over the raw request body, comparing in constant time, and rejecting timestamps outside a freshness window (300 seconds is recommended):

import crypto from "node:crypto";

const FRESHNESS_TOLERANCE_SECONDS = 300;

export function verifyWebhookSignature(
  body: Buffer,
  header: string | undefined,
  secret: string,
): boolean {
  if (!header) return false;

  const match = header.match(/^t=(\d+),v1=([0-9a-f]+)$/);
  if (!match) return false;

  const timestamp = Number(match[1]);
  const provided = Buffer.from(match[2], "hex");

  const nowSeconds = Math.floor(Date.now() / 1000);
  if (Math.abs(nowSeconds - timestamp) > FRESHNESS_TOLERANCE_SECONDS) return false;

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

  if (provided.length !== expected.length) return false;
  return crypto.timingSafeEqual(provided, expected);
}

The signed input is the raw request body — verify before any JSON parsing or normalization. The body must be the exact bytes the request carried; reserializing a parsed object produces a different HMAC.

Deduplicate on X-Beliq-Event-Id (the envelope id): store delivered ids and skip repeats. The id is the same across all retries of an event; the timestamp t is re-signed on each attempt, so never treat (id, t) as a uniqueness pair — dedup on the id alone.

A manual resend carries the original event id. Pressing Resend on a delivery in the dashboard replays the same evt_…, so a handler following the advice above will correctly recognise it as a duplicate and discard it — while the delivery log records your 2xx and shows the resend as successful. That is the intended behaviour of both halves and it is a confusing pair to meet for the first time during an incident. When you are resending because your handler dropped the event, clear that id from your dedup store first, or reconcile from the API rather than the replay.

Deliveries are not ordered. Events are dispatched as they are produced and each retries on its own schedule, so a job.completed from a later request can arrive before an earlier one, and a retried event can arrive after events created long after it. Do not infer sequence from arrival order: use the envelope’s created_at, and treat each event as a statement about its own subject rather than a step in a stream.

Beliq attempts the first delivery immediately, then retries failures up to 7 attempts total with increasing backoff:

After the final attempt the delivery is marked failed. Each attempt has a 10-second timeout.

• 2xx — delivery succeeds.
• 3xx — treated as a failure; redirects are not followed. Register the final URL directly.
• 4xx / 5xx or a connection error — retried until the schedule is exhausted.
• An inactive or removed endpoint stops delivery immediately.

Return a 2xx status as soon as you have accepted the event; do the work afterward. Inspect past deliveries and retry state in the dashboard delivery log.

An endpoint stops receiving events in three ways, and all three lose the events that occur while it is stopped.

You pause it. Pausing takes effect immediately, including for deliveries already scheduled to retry.

Beliq disables it. When a delivery exhausts the full seven-attempt schedule — roughly 35 hours of failures — the endpoint is disabled automatically. The organization’s owners and admins are emailed, each subject to their own notification preferences. The dashboard shows such an endpoint as auto-disabled together with the reason, distinct from a pause you performed, and re-enabling it clears that state.

You delete it. Deliveries stop and the endpoint’s delivery history goes with it.