AbuseZero

Webhooks

Receive AbuseZero events at your own HTTPS endpoints as they happen. Signed, retried, filtered and logged.

Webhooks send AbuseZero events to your own HTTPS endpoints as they happen. Every evaluation result, outcome change, allow and block list change and finished background job reaches your systems as a signed request, without polling.

Why it matters

Your server already receives each evaluation's result in the response. Webhooks bring that result, and everything that happens after it, to the systems that weren't part of the request: a fraud review queue, a data warehouse, an alerting channel or your CRM. They also report work that finishes later, such as imports, exports and data deletions, and changes your team makes in the dashboard, such as a new block list entry.

Key capabilities

  • Recorded with the change. An event is recorded together with the change it describes, for every endpoint subscribed at that moment. Every evaluation that returns allow or deny sends its evaluation.completed event, and a request that fails never sends one. An endpoint added later receives events from then on.
  • Signed per endpoint. Every request is signed with the endpoint's own signing secret, so your server can prove it came from AbuseZero and that the body wasn't changed.
  • Retried with identical bytes. A delivery that doesn't receive a 2xx reply is attempted up to 6 times over 12 hours. Every attempt carries the same event ID and the same body, so one duplicate check covers every retry.
  • The REST API's own envelopes. Each event's data is the object the AbuseZero REST API returns, built from the same public fields. Evidence and the request details your server sent are never included.
  • Filtered per endpoint. Each endpoint chooses its events, can be limited to chosen benefits, and can receive denied evaluations only.
  • A complete delivery log. Every delivery keeps its exact request body and each attempt's status code, timing and reply for 30 days. Read it in the dashboard, the AbuseZero REST API, the AbuseZero CLI or the AbuseZero MCP server, and send any delivery again.
  • Failing endpoints handled. An endpoint that fails every delivery for 3 days is paused, and the workspace owner and admins are emailed. Resume it once it's fixed.
  • Rotation without downtime. After you rotate a signing secret, the previous secret keeps signing beside the new one for 24 hours.

How delivery works

Evaluate, report, changeSigned POST request2xx within 10 secondsYour productAbuseZeroYour endpoint
Evaluate, report, changeSigned POST request2xx within 10 secondsYour productAbuseZeroYour endpoint
  1. Something happens in your workspace, for example an evaluation returns deny.
  2. AbuseZero records the event, with one delivery for each active endpoint that subscribes to it.
  3. AbuseZero sends the event to each endpoint as a signed POST request. A 2xx reply within 10 seconds completes the delivery.
  4. Any other reply, or none, schedules the next attempt. See Retries.

Delivery is at least once, and events can arrive in a different order from the one they happened in. Use the event id to skip events you already handled. Use the object's own fields, such as an outcome's state and previous_state, to decide what's current.

Events

EventSent when
evaluation.completedAn evaluation returns allow or deny, including on benefits in observe mode.
evaluation.skippedAn evaluation doesn't run: the workspace is out of credits, a payment is overdue, the service is inactive or the benefit is paused.
outcome.updatedAn outcome report changes an outcome's state, a grant after a deny is recorded, an import changes an outcome, or an outcome passes its due time.
access_list_entry.createdAn allow or block list entry is added.
access_list_entry.deletedAn allow or block list entry is deleted.
import.completedAn import finishes applying its rows.
export.completedAn export is ready to download.
data_deletion.completedA user's data deletion finishes.
webhook.testA test event is sent to the endpoint.

Previews, Test console runs, simulations and replays send no events. Every event type and its payload is in Webhook events.

Configuration

The workspace owner and admins add and change endpoints in Developers → Webhooks. No API key, OAuth token or machine client can add or change an endpoint, so a credential can never send your workspace's events to a new destination.

SettingValues
Endpoint URLAn HTTPS URL on a public host name, up to 2,048 characters, with no IP address, user name, password or # fragment. It can't be changed later: a new destination is a new endpoint.
DescriptionOptional, up to 200 characters.
EventsOne or more event types. webhook.test is sent only when someone sends a test event.
BenefitsOptional, up to 50. Events tied to other benefits aren't sent. Events tied to no benefit, such as imports, exports, data deletions and list entries for every benefit, are always sent.
Denied evaluations onlySend evaluation.completed only when result is deny. In observe mode every result is allow, so this endpoint receives no evaluation.completed events from benefits in observe mode.

Each workspace can have up to 10 endpoints. Each endpoint has its own signing secret, starting with whsk_. It's shown once when the endpoint is added, and once after each rotation.

Programmatic access

InterfaceUse
AbuseZero REST APIGET /v1/webhook-endpoints, GET /v1/webhook-endpoints/{id}, POST /v1/webhook-endpoints/{id}/test, GET /v1/webhook-deliveries, GET /v1/webhook-deliveries/{id}, POST /v1/webhook-deliveries/{id}/resend
AbuseZero Node.js SDKverifyWebhook() for every request your endpoint receives, and call() for the endpoints above
AbuseZero CLIabusezero webhook-endpoints list, get, test and abusezero webhook-deliveries list, get, resend
AbuseZero MCP serverabusezero_list_webhook_endpoints, abusezero_get_webhook_endpoint, abusezero_send_webhook_test, abusezero_list_webhook_deliveries, abusezero_get_webhook_delivery, abusezero_resend_webhook_delivery
DashboardDevelopers → Webhooks

Deliveries and credits

Each plan includes a number of webhook deliveries every calendar month (UTC). Beyond them, deliveries use credits. Every attempt that reaches your endpoint counts as a delivery, including retries and resends. Test events and attempts that fail on AbuseZero's side never count. The included deliveries for each plan are on the pricing page, and your workspace's usage and rate are in Workspace settings → Billing & Subscriptions. The full list is in What counts as a delivery.

Response data

Every request body is one event:

{
  "object": "event",
  "id": "evt_9b3e7c21-4d6a-4f58-a1e2-7c0d5b8f3a64",
  "type": "outcome.updated",
  "api_version": "v1",
  "created_at": "2026-10-29T14:20:03.000Z",
  "workspace": "ws_2c8f4a1d-7e3b-4c69-9d05-6a1f3e7b2c48",
  "data": {
    "object": "outcome",
    "id": "out_5a9c3e17-2b4d-4f80-9c6e-1d7b3a5f8e02",
    "evaluation": "eval_3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a0c4e93",
    "state": "granted",
    "source": "evaluation",
    "occurred_at": "2026-10-29T14:02:47.000Z",
    "due_at": "2026-11-05T14:02:47.000Z",
    "previous_state": "awaiting_outcome"
  }
}

The request carries three signature headers: abusezero-webhook-id, abusezero-webhook-timestamp and abusezero-webhook-signature. See Signatures.

Next steps

Receive webhooks

Add an endpoint, verify every request and confirm deliveries.

Webhook events

Every event type, header and payload.

Webhook deliveries API

Read the delivery log and send a delivery again.

How is this guide?

Last updated on

Outcomes

Whether a user actually received a benefit after its evaluation, and how that history protects every claim that follows.

Allow and block lists

Decide specific users, email addresses, domains, IP addresses or devices outright, for one benefit or all of them.

On this page

Why it mattersKey capabilitiesHow delivery worksEventsConfigurationProgrammatic accessDeliveries and creditsResponse dataNext steps