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#