Receive webhooks

Add an endpointCopy Anchor Link

1. In the dashboard, open Developers → Webhooks and select Add endpoint.
2. Enter the Endpoint URL.
3. Under Events, check the events you need. evaluation.completed is checked to start.
4. Optionally check Denied evaluations only, and choose Benefits to limit the endpoint to them.
5. Select Add endpoint, then copy the signing secret.

The signing secret starts with whsk_ and is shown once. Store it where your server reads secrets, for example as ABUSEZERO_WEBHOOK_SECRET. Each endpoint has its own secret.

Read the raw request bodyCopy Anchor Link

The signature covers the exact bytes AbuseZero sent. Read the body as text or bytes, and verify it before you parse it. A body that was parsed and serialized again won't match its signature.

Verify the signatureCopy Anchor Link

Pass the raw body, the request headers and the signing secret to verifyWebhook(). It returns the event, or throws WebhookVerificationError when the request isn't from AbuseZero, was changed, or is more than 5 minutes old.

import { verifyWebhook, WebhookVerificationError } from "abusezero/server";
import { enqueue } from "@/lib/jobs";

export async function POST(request: Request) {
  const payload = await request.text();

  let event;
  try {
    event = verifyWebhook({ payload, headers: request.headers, secret: process.env.ABUSEZERO_WEBHOOK_SECRET! });
  } catch (error) {
    if (error instanceof WebhookVerificationError) return new Response(null, { status: 400 });
    throw error;
  }

  await enqueue("abusezero-event", event); // Your own queue. Handle the event after replying.
  return new Response(null, { status: 204 });
}

enqueue stands for your own job queue.

Verify in other languagesCopy Anchor Link

Every request carries three AbuseZero signature headers. Verify them in this order:

1. Read abusezero-webhook-id, abusezero-webhook-timestamp and abusezero-webhook-signature. Refuse the request if one is missing.
2. Refuse the request if abusezero-webhook-timestamp, in Unix seconds, is more than 5 minutes from your server's clock.
3. Build the signed content: {abusezero-webhook-id}.{abusezero-webhook-timestamp}.{raw body}.
4. Take the signing secret without its whsk_ prefix and decode it from base64. That is the key.
5. Compute HMAC-SHA256 of the signed content with the key, and encode it as base64.
6. abusezero-webhook-signature holds one or more values separated by spaces, each starting with v1,. Compare your result with each value after v1,, in constant time. Accept the request if one matches.
7. Parse the body, and check that its id equals abusezero-webhook-id.

import base64, hashlib, hmac, json, time

def verify_abusezero_webhook(body: bytes, headers, secret: str, tolerance: int = 300) -> dict:
    event_id = headers["abusezero-webhook-id"]
    timestamp = headers["abusezero-webhook-timestamp"]
    if abs(time.time() - int(timestamp)) > tolerance:
        raise ValueError("The webhook timestamp is outside the tolerance.")

    key = base64.b64decode(secret.removeprefix("whsk_"))
    signed = f"{event_id}.{timestamp}.".encode() + body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()

    offered = [value[3:] for value in headers["abusezero-webhook-signature"].split(" ") if value.startswith("v1,")]
    if not any(hmac.compare_digest(expected, value) for value in offered):
        raise ValueError("The webhook signature doesn't match.")

    event = json.loads(body)
    if event.get("id") != event_id:
        raise ValueError("The webhook body doesn't match its headers.")
    return event

Reply quickly, then processCopy Anchor Link

Reply with a 2xx status within 10 seconds. A slower reply counts as a failed attempt and is retried, even if your server finished the work. Put the event on your own queue, reply, then process it.

• Reply 2xx to event types your endpoint doesn't handle. New event types can be added within v1.
• A redirect is not followed and counts as a failed attempt. Use the final URL when you add the endpoint.
• The first 1 KB of your reply is kept in the delivery log. A short reason in the body makes failed attempts easier to read later.

Skip duplicatesCopy Anchor Link

Delivery is at least once. A retry, a resend or a network failure after your server replied can bring the same event again, always with the same id. Record each id you finish, and skip it the next time.

import type { WebhookEvent } from "abusezero/server";
import { db } from "@/lib/db";

export async function handleAbuseZeroEvent(event: WebhookEvent) {
  await db.transaction(async tx => {
    const first = await tx.insertIfAbsent("handled_abusezero_events", { id: event.id });
    if (!first) return; // Already handled.

    switch (event.type) {
      case "evaluation.completed": return onEvaluation(tx, event.data);
      case "outcome.updated": return onOutcome(tx, event.data);
      default: return; // Event types you don't handle.
    }
  });
}

db, insertIfAbsent, onEvaluation and onOutcome stand for your own code. Events can also arrive out of order. Act on the state each object carries, such as an outcome's state, rather than on arrival order.

Send a test eventCopy Anchor Link

In Developers → Webhooks, open the endpoint's actions menu and select Send test event. From the dashboard it's usually sent within a minute. Through the AbuseZero REST API it's sent right away:

const delivery = await abusezero.call("/v1/webhook-endpoints/whe_7d2e9a40-3c1b-4f65-8e27-b9a0c4d61f53/test", {
  method: "POST",
  idempotencyKey: "webhook-test-2026-10-31",
});

The AbuseZero CLI command is abusezero webhook-endpoints test, and the AbuseZero MCP server tool is abusezero_send_webhook_test. Test events are free, are sent even to a paused endpoint, are attempted once, and each endpoint accepts 10 an hour.

Check the delivery logCopy Anchor Link

Select Deliveries on the endpoint's row. The test event shows Delivered with your endpoint's status code. Open it with View to see the exact request body, the abusezero-webhook-id header and every attempt.

To read the log from code, call GET /v1/webhook-deliveries with endpoint_id, or run abusezero webhook-deliveries list --endpoint-id whe_…. A delivery that failed for a reason on your side shows the error and your reply. Delivery errors lists each one.

You now have an endpoint that receives signed AbuseZero events, refuses anything else, replies within its time limit and processes each event once.