# Testing webhooks

Queue a webhook.test delivery from the dashboard or the API, forward sandbox events to localhost with webhooks listen, and cause real events with events trigger.


There are three ways to exercise a receiver before it handles live traffic. A test send goes through the real queue, signing and retries. The CLI listener brings sandbox events to a server on your own machine, which a registered endpoint cannot reach because private addresses are refused. The trigger command creates real records in the sandbox so that genuine events fire.

## Send a test event

In the dashboard, open **Developers**, tab **Webhooks**, choose the endpoint and press **Send test**. The confirmation **Test event sent** appears and the delivery shows in the endpoint's list. Opening it shows the **Payload sent**, each attempt with its status and duration, and the **Response body** your server returned.

The same action through the API needs `developer:write`:

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

The answer is `202` with the queued delivery:

```json
{
  "id": "dlv_2kP8aQ5mZr1NcV7xT3bLwE9fGyU",
  "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
  "webhook_id": "whk_2kP7vR3nXq9LmT4bW8cYzF1dHsJ",
  "url": "https://erp.example.test/hooks/billing",
  "event_id": "wev_2kP8aQ4kYt6HdS2wR9nMjC5vBxA",
  "event_type": "webhook.test",
  "status": "pending",
  "attempts": 0,
  "max_attempts": 15,
  "next_attempt_at": "2026-11-19T08:05:12.640391Z",
  "duration_ms": 0,
  "created_at": "2026-11-19T08:05:12.640391Z",
  "sequence": 1
}
```

The event's `data.attributes` holds `{"message": "This is a test event."}`. Read `GET $BUSINESS_API/developer/deliveries/{id}` a few seconds later to see the attempt in `history`. A disabled or paused endpoint answers `409`: resume it first.

## Forward events to localhost

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

On start the command opens a temporary endpoint on the server (`POST /developer/cli-sessions`) and prints its `whsec_` signing secret, valid for this session only. It then waits for new events (`GET /developer/cli-sessions/{id}/events`, which holds the request for up to 25 seconds) and POSTs each one to `--forward-to` with the full body and the same three headers, signed by the server. Each forward prints one line with the event type, its `wev_` identifier, your status code and the time taken. On exit the command ends the session; if the CLI stops polling, the session expires after about 90 seconds. The one difference from real deliveries is that `webhook-id` carries the event identifier. Against a server without CLI sessions the command falls back to reading `GET /developer/events` every `--poll-interval`. On a live context it refuses to start unless you pass both `--live` and `--confirm-live`. The key needs `developer:write` to open the session and `developer:read` to poll it.

## Cause real events

```bash
gotactl events trigger invoice.paid
```

This issues a sandbox invoice and pays it through the simulated payment connector, so `invoice.paid` fires for real. `gotactl events trigger --list` shows the supported types: `customer.created`, `account.created`, `invoice.issued`, `invoice.paid`, `payment.received`, `reading.accepted` and `webhook.test`, which sends a test to the first endpoint configured. Every event then appears in **Developers**, tab **Events**, with the deliveries it produced.

## Next steps

- [Check signatures on what your receiver gets](/docs/webhooks/verify)
- [What the delivery statuses mean](/docs/webhooks/retries)
- [Every CLI command and flag](/docs/cli/overview)
- [What the sandbox contains](/docs/getting-started/sandbox)

