Subscribe an endpoint
Two ways to start receiving events — from Settings, or with a key an app holds.
From Settings
Navigate to: Settings → API keys & webhooks → Webhooks → Add endpoint (Super Administrator)
One business may hold up to 20 endpoints. Every matching event is POSTed here.
Tick exactly what you want from the catalogue. Nothing else is sent.
A whsec_… secret is shown once, with the verification snippet. It is stored encrypted and never shown again — if you lose it, Rotate secret issues a new one and the old one stops signing immediately.
Test on the endpoint row emits a real ping event through the whole pipeline — the same queue, the same signing, the same log. What you see in Deliveries is what production will do.
From an app, with a key
An app such as Zapier or Make cannot ask a person to visit Settings for every automation. A key minted with Allow webhook subscriptions may manage its own endpoints:
| Endpoint | Does |
|---|---|
| GET /api/v1/webhooks/events | The event catalogue |
| GET /api/v1/webhooks/endpoints | This business's endpoints — the secret is never returned |
| POST /api/v1/webhooks/endpoints | Subscribe. `{ url, events[], description? }` → 201, secret returned once |
| DELETE /api/v1/webhooks/endpoints/{id} | Unsubscribe |
| POST /api/v1/webhooks/endpoints/{id}/test | Queue a ping → 202 |
curl -X POST https://api.trabalance.com/api/v1/webhooks/endpoints \
-H "Authorization: Bearer tk_live_…" \
-H "Content-Type: application/json" \
-d '{ "url": "https://hooks.example/trabalance",
"events": ["invoice.created", "invoice.paid"],
"description": "Order desk" }'Endpoints created this way are ordinary endpoints: they appear under Settings → Webhooks, sign identically, and share the same delivery log. events accepts "*" for everything.
Without the Allow webhook subscriptions option the same call answers 403 insufficient_scope — "This key was not minted with the Webhooks option." Mint a new key with it on; there is no way to add it to an existing key.
An OAuth app instead
An application does not create per-business endpoints. Set one webhook URL on the app, subscribe to event types on its Webhooks tab, and deliveries arrive for every business that authorised the app and still holds a live access token. Signing uses the app's own webhook signing secret.
Related
- Webhooks — the envelope and headers
- Available events
- Signature verification
- The delivery log