Listen to webhook events

Receive signed events on your server, check the Standard Webhooks headers, test locally with the CLI and register the permanent endpoint through the API.

What you will build#

An HTTP receiver that accepts only correctly signed deliveries, wired first to your own machine through the CLI and then registered as one of the company's permanent endpoints. By the end you have an active whk_ endpoint subscribed to payment.received and invoice.paid, and you have watched a test delivery arrive and get a 200.

Every delivery is a POST with a JSON body and three headers: webhook-id, webhook-timestamp (Unix seconds) and webhook-signature, formatted as v1,<base64>. The signature is an HMAC-SHA256 over id.timestamp.body, keyed with the endpoint's whsec_ secret. While a secret is being rotated, the header carries two space-separated v1, values, one per secret.

Prerequisites#

  • An active sandbox, and the gotactl CLI signed in to it (gotactl auth login).
  • A test API key holding developer:write (to create the endpoint and send the test) and developer:read (to read deliveries).
  • Node.js 20 or later to run the sample receiver in examples/webhook-receiver; the same folder has Python and Go versions.

1. Forward sandbox events to your machine#

An endpoint URL must be public https, so localhost is refused. While you develop, the CLI reads the sandbox's events and re-sends them, signed, to a local URL.

bash
gotactl webhooks listen --forward-to http://localhost:3000/hook --events payment.received,invoice.paid

--events restricts forwarding to a comma-separated list of types, and --poll-interval sets how often the CLI checks for new events against a server without CLI sessions (default 1s). Against a live context the command runs only with both --live and --confirm-live.

2. Start the receiver with that secret#

In a second terminal, from the examples/webhook-receiver folder:

bash
WEBHOOK_SECRET="whsec_/zemf1hlS/YnhOJXSiMlQtDMjsSCnb3T2EH3ZndfbrU=" node node/server.mjs

The receiver answers 400 to any request that lacks one of the three headers, whose webhook-timestamp is more than 300 seconds away from the current time, or whose signature does not match.

3. Trigger a real event#

bash
gotactl events trigger invoice.paid

The command issues an invoice in the sandbox and pays it through the simulated payment connector, so it produces both payment.received and invoice.paid.

4. Register the permanent endpoint#

Once the receiver runs at an https address reachable from the internet, register it. The URL may not contain credentials or a fragment, is limited to 2048 characters and must resolve to a public address.

bash
curl -sS -X POST "$BUSINESS_API/developer/webhooks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://erp.example.test/hooks/billing","description":"ERP: collections and paid invoices","events":["payment.received","invoice.paid"]}'

201 Created response, abridged:

json
{
  "id": "whk_3d68SShcDvNgBfM7XueBaFfs63I",
  "url": "https://erp.example.test/hooks/billing",
  "description": "ERP: collections and paid invoices",
  "events": ["payment.received", "invoice.paid"],
  "enabled": true,
  "created_by": "key_3f5kSeI9SXDLwgbb5hilkGVvprT",
  "created_at": "2026-11-19T09:12:44Z",
  "updated_at": "2026-11-19T09:12:44Z",
  "secret": "whsec_YUxdKD/3IFzwZ1TJmMdEtQDKO9Lmv4squeePTNoymRo="
}

5. Send a test delivery#

bash
curl -sS -X POST "$BUSINESS_API/developer/webhooks/whk_3d68SShcDvNgBfM7XueBaFfs63I/test" \
  -H "Authorization: Bearer $API_KEY"

Test it#

Follow the delivery with GET $BUSINESS_API/developer/webhooks/whk_3d68SShcDvNgBfM7XueBaFfs63I/deliveries: its status turns to succeeded once your server replies with a 2xx code. In the dashboard, open Developers, then the Webhooks tab, pick the endpoint and press Send test; the Deliveries list shows each attempt with its status and the HTTP code your server returned.

When your server fails, the delivery is retried after 30 s, 2 min, 10 min, 30 min, 1 h, 2 h, 4 h and 8 h, then every 12 hours, up to 15 attempts or 72 hours. A 410 pauses the endpoint itself, and its deliveries wait as paused until someone presses Resume. Any other 4xx is retried twice and the delivery is then held as paused; once the receiver is fixed, Resend failed in the endpoint's menu puts held and failed deliveries back in the queue.

Next steps#