Anonyx

Webhooks

Anonyx webhooks send an HTTP POST request to your server whenever an event happens on an anonymization project. They are the recommended push mechanism for reacting in real time to a completed run, a failure or a cancellation — no polling required.

Each webhook is attached to a project: every project owns its own independent list of webhooks, with their target URLs, secret and event selection.

Creating and managing a webhook

You can create and manage a project's webhooks in two complementary ways.

From the UI

From your dashboard, open the relevant project and the Webhooks tab to create, enable, test or delete an integration without writing any code.

/projects/{projectId}/webhooks

From the REST API

The POST /webhooks, PUT /webhooks/{id}, DELETE /webhooks/{id} and POST /webhooks/{id}/test endpoints expose the full lifecycle.

See the API reference →

Webhook access depends on your subscription.

Supported events

When you create a webhook, you select one or more events you want to subscribe to.

EventDescription
run_completedAn anonymization run finished successfully.
run_failedAn anonymization run failed (connection error, invalid rule, etc.).
run_cancelledA run was cancelled manually or automatically before completion.

Payload format

Webhooks are delivered as POST requests with a Content-Type of application/json. The request body always follows this structure:

application/json
{
  "event": "run_completed",
  "run_id": "5f9c2c84-2a3a-4b2b-9b6a-2f7f0a4b9c1d",
  "project_id": "1a2b3c4d-5e6f-7890-abcd-ef0123456789",
  "timestamp": "2026-05-23T12:00:00.000Z",
  "data": {
    "status": "succeeded",
    "rows_processed": 124530,
    "duration_ms": 18742
  }
}

Security and signature verification

Every webhook has a unique secret returned at creation time. Anonyx uses it to compute an HMAC-SHA256 over the raw POST body and sends the result as an HTTP header. Always verify this signature on your server before processing the event.

  • X-Anonyx-Signature — HMAC-SHA256 signature in the sha256=<hex> format, computed over the raw JSON body.
  • X-Anonyx-Event — delivered event type (run_completed, run_failed or run_cancelled).
  • X-Anonyx-Delivery-Id — unique delivery identifier, useful for idempotency and log correlation.

Target URLs must use HTTPS. Plain-text URLs are rejected at creation time.

Verification examples

import crypto from 'node:crypto';

export function verifyAnonyxSignature(
  rawBody: string,
  headerValue: string,
  secret: string,
): boolean {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(headerValue),
  );
}

Retries and timeouts

Anonyx considers a delivery successful as soon as it receives a 2xx response within 10 seconds. Otherwise, the request is retried using an exponential backoff policy.

  • Up to 5 attempts per event.
  • Exponential backoff: 5 s, 25 s, 125 s, 625 s, then 3,125 s between attempts.
  • Any HTTP 2xx response marks the delivery as successful.
  • The per-attempt timeout is 10 seconds.

Best practices

  • Use X-Anonyx-Delivery-Id as an idempotency key — the same event may be delivered multiple times when retried.
  • Respond within 10 seconds, otherwise the request is treated as a failure and retried.
  • If your processing is long, acknowledge the request quickly (200) and process the payload in an asynchronous queue.
  • Store the webhook secret on the server side only and rotate it regularly via the API or the UI.