Webhooks

A webhook is an HTTPS endpoint you register with AACSearch. When something happens in your organization — an experiment finishes, a hosting configuration changes, a support thread is created — AACSearch sends a signed POST to that endpoint with a JSON body describing the event.

Webhooks are push, not poll. They carry no API key: the receiver proves the request came from AACSearch by verifying an HMAC signature.

Before you begin

• An organization where you are an owner or admin. Any member can read the list and send a test; creating, editing, rotating and deleting require one of those two roles.
• A public HTTPS endpoint that accepts POST and returns 2xx quickly.
• A way to read a request body before parsing it as JSON — signature verification needs the exact bytes.

What you'll build

An endpoint that verifies every delivery and acknowledges it, plus an alerting view of failures.

Steps

1. Create the endpoint

Open Webhooks in the console (/dashboard/webhooks) and choose New webhook. Enter:

• a name (up to 120 characters),
• an endpoint URL (up to 2048 characters, HTTP or HTTPS),
• the events to receive — either individual events, or All events.

Expected result: the endpoint appears in the list, enabled, with a "No deliveries yet" status.

Verify: press Send test. This creates a real delivery of a webhook.test event. Your endpoint should receive it within a few seconds, and the row's status should turn to success on Refresh.

2. Read the delivery

Every request is a JSON POST with these headers:

The body is the envelope — your data is in data:

{
  "id": "dlv_01J…",
  "event": "experiment.promoted",
  "created_at": "2026-09-16T10:32:11.482Z",
  "organization_id": "org_01J…",
  "data": { "experiment_id": "8c1f…", "variant_id": "popular" }
}

3. Verify the signature

v1 is a hex HMAC-SHA256 of `${t}.${rawBody}` keyed by your whsec_… secret. Compute it over the raw body, then compare in constant time.

import { createHmac, timingSafeEqual } from "node:crypto";

/** Returns true only for a fresh, unmodified, correctly signed delivery. */
export function verifyWebhook(
  secret: string,
  rawBody: string,
  signatureHeader: string,
  toleranceSeconds = 300,
): boolean {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((part) => part.split("=") as [string, string]),
  );
  const timestamp = Number(parts.t);
  const provided = parts.v1;
  if (!Number.isFinite(timestamp) || !provided) return false;

  // Reject replays of an old delivery.
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;

  const expected = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(provided, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

Verify: send a test delivery and log the computed value alongside the header. They must be equal. Then change one character of the secret and confirm your verifier returns false.

4. Acknowledge quickly, process afterwards

Return 2xx as soon as the signature is verified, then do the work asynchronously. A slow receiver is treated the same as a failing one.

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const rawBody = await request.text();
    const signature = request.headers.get("X-AACSearch-Signature") ?? "";

    if (!verifyWebhook(env.WEBHOOK_SECRET, rawBody, signature)) {
      return new Response("invalid signature", { status: 401 });
    }

    const delivery = JSON.parse(rawBody);
    const id = request.headers.get("X-AACSearch-Delivery") ?? delivery.id;

    // Deduplicate: delivery is at-least-once (see "Retries" below).
    if (await env.SEEN.get(id)) return new Response("ok", { status: 200 });
    await env.SEEN.put(id, "1", { expirationTtl: 86_400 * 3 });

    await env.QUEUE.send({ event: delivery.event, data: delivery.data });
    return new Response("ok", { status: 200 });
  },
};

Verify: the console's delivery row shows a 2xx HTTP code and attempt count 1.

Retries and idempotency

A delivery is at-least-once. Failed attempts are retried with exponential backoff and full jitter:

An attempt is retried only when the failure might clear on its own:

Because a retry can follow an attempt whose response you never saw, your handler must be idempotent. Key on X-AACSearch-Delivery (as in step 4) and make the side effect safe to repeat.

Verify: point an endpoint at a URL that returns 500. The console shows the delivery retried with a growing delay, still pending, until the sixth attempt marks it failed.

Events you can subscribe to

* No group in the console picker — subscribe with All events.

A webhook's events list may also be the wildcard *, which covers every event including ones added later. webhook.test is sent only by Send test and is not subscribable.

Inspect deliveries

The endpoint's detail page lists the 100 most recent deliveries with their event, status, HTTP code, attempt count and time. A row opens the full record: status, HTTP code, attempts, created and finished timestamps, the error text, and the exact JSON request body with a copy action.

Use it to tell these apart:

Next

• Errors and retries — the API-side error contract and idempotency.
• A/B experiments — the experiment.* events in context.
• Organization and billing — roles that may manage webhooks.