# 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`.

✓ Checkpoint: the CLI prints this session's signing secret, starting with `whsec_`. Copy it; a new one is generated every time the command starts.

## 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.

✓ Checkpoint: the process prints `listening on http://127.0.0.1:3000/hook`.

## 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`.

✓ Checkpoint: the `webhooks listen` terminal shows one line per forwarded event, such as `2026-11-19T09:10:02Z  --> invoice.paid [wev_3x6bknQybCmscpyDKTJXSdTOBT7]  <-- 200 OK (8ms)`, and the receiver prints `verified event invoice.paid` followed by the event `id`.

## 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="
}
```

✓ Checkpoint: `secret` is filled in. Put it in your secret store now, because later reads of the endpoint never return it. Send `["*"]` as `events` to receive every type in the catalog.

## 5. Send a test delivery

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

✓ Checkpoint: the `202` response holds a delivery with `"event_type": "webhook.test"`, `"status": "pending"` and an `id` starting with `dlv_`. A paused or disabled endpoint answers `409` instead.

## 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

- [Verify signatures in Node.js, Python and Go](/docs/webhooks/verify)
- [Retry schedule and bulk redelivery](/docs/webhooks/retries)
- [Good practice: reply fast and drop duplicates by webhook-id](/docs/webhooks/best-practices)
- [Receive payments and confirm settlement by webhook](/docs/guides/receive-payments)

