Webhooks

A webhook sends a message to an address of yours every time a chosen event happens in your workspace, for example a new purchase. When you finish, you will have an active webhook, a signing secret to verify its messages, and a place to watch deliveries. Webhooks are part of every current Zanfia plan.

Add a webhook

Events you can subscribe to

The 14-day notice is sent only for access lasting at least 3 months.

What a delivery looks like

Every delivery is an HTTP POST with a JSON body and these headers, plus any custom headers and basic auth you configured:

The body always has the same envelope. The keys listed under data are always present and are null when the event carries no value for them; an event can add its own extra keys (for a purchase: productName, paymentType, quantity, price).

{
  "apiVersion": "2026-07-13",
  "event": "product.ProductPurchased",
  "occurredAt": "2026-09-30T10:00:00.000Z",
  "workspaceId": "your workspace id",
  "data": {
    "clientId": "cli_4f81c92a7b3d",
    "clientEmail": "anna.novak@example.com",
    "clientFirstName": "Anna",
    "clientLastName": "Novak",
    "clientName": "Anna Novak",
    "productId": "prod_8c31a2f4d95e",
    "priceId": "price_5e92c7d1a48b",
    "orderId": "35e479ee-d456-4ee9-a5da-e7ff8109ffcc",
    "checkoutId": "chk_1f83b6a92c4d",
    "orderTotalAmount": 199,
    "consents": [{ "name": "marketing", "value": true }],
    "utmSource": "facebook",
    "utmMedium": "cpc",
    "utmCampaign": "summer-launch",
    "utmTerm": null,
    "utmContent": null
  }
}

The preview box in the editor shows the body for whichever event you select, so use it as the reference for each event's extra keys.

Verify the signature

Each delivery carries X-Zanfia-Signature: t=[unix time],v1=[signature]. The signature is the HMAC-SHA256, in hex, of the text [t].[raw body] (the t value, a dot, then the request body exactly as received), computed with your signing secret. On your server:

1. Read t and v1 from the header.
2. Compute HMAC-SHA256 over t, a dot and the raw request body, with the whsec_ secret as the key.
3. Compare your result with v1 using a constant-time comparison, and reject the request if they differ.

Compute over the raw body, before any JSON parsing; a re-serialized body produces a different signature.

Monitor, redeliver, pause and delete

The list at /workflows/webhooks has four columns: Endpoint, Events, Health and Active.

Click a row to open Webhook details: the address, its state, its events, and Recent deliveries with time, status and response. The redeliver arrow on a delivery sends that event again through the webhook's current settings ("Delivery re-sent - endpoint responded 200"). The buttons at the bottom are Delete ("Delete this webhook?"), Send test and Edit.

To pause a webhook without deleting it, turn its Active switch off in the list; it stops receiving events until you turn it back on.

Webhooks inside workflows

If a workflow of yours contains a webhook action, its address appears in a second table, Used in workflows, with the workflows that call it and the same health and delivery history. Those endpoints are edited in the workflow itself, not here. See Build a workflow for workflows.