How webhooks work
Register an HTTPS endpoint, choose event types and receive each change as a signed Standard Webhooks POST with a v1 JSON envelope.
A webhook is an HTTPS address you register for your utility. Whenever something you subscribed to changes, such as an invoice being paid or a reading being accepted, the server stores an event and queues one delivery per subscribed endpoint. A background worker then POSTs the event to your address, signs it, and retries it until your server answers 2xx or the delivery runs out of time.
You can manage endpoints in the dashboard under Developers, tab Webhooks, or through the API. The API operations need an API key with developer:read to read and developer:write to change anything.
Endpoints in the API#
| Operation | Method and path |
|---|---|
| List or create endpoints | GET, POST $BUSINESS_API/developer/webhooks |
| Read, change or delete one | GET, PATCH, DELETE $BUSINESS_API/developer/webhooks/{id} |
| Rotate the signing secret | POST $BUSINESS_API/developer/webhooks/{id}/roll |
| Queue a sample event | POST $BUSINESS_API/developer/webhooks/{id}/test |
| Follow its deliveries | GET $BUSINESS_API/developer/webhooks/{id}/deliveries |
| See every event type | GET $BUSINESS_API/developer/event-types |
Register an endpoint#
The url must use https and must not point at a private, loopback or link-local address; internal host names such as localhost are refused too. events takes event type names, or * for all of them, and description holds up to 512 characters.
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 billing sync", "events": ["invoice.paid", "payment.received"]}'
The 201 response carries secret, a value starting with whsec_. Store it now: reads leave it out, and the only other response that shows a secret is the one from rotating it, which returns the new value. Reading the endpoint afterwards returns:
{
"id": "whk_2kP7vR3nXq9LmT4bW8cYzF1dHsJ",
"tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
"url": "https://erp.example.test/hooks/billing",
"description": "ERP billing sync",
"events": ["invoice.paid", "payment.received"],
"enabled": true,
"created_by": "usr_2mB4tK9qWx1RfZ7nLc3VhP8sDjE",
"created_at": "2026-11-19T08:02:41.118204Z",
"updated_at": "2026-11-19T08:02:41.118204Z",
"health": "healthy",
"consecutive_failures": 0,
"api_version": "v1"
}
What arrives at your server#
Each delivery is a POST with Content-Type: application/json and three signature headers: webhook-id (the delivery's dlv_ identifier), webhook-timestamp (Unix seconds) and webhook-signature. The body is the event envelope:
{
"api_version": "v1",
"created_at": "2026-11-19T08:05:12.640391Z",
"data": {
"attributes": {"message": "This is a test event."},
"resource": {"id": "whk_2kP7vR3nXq9LmT4bW8cYzF1dHsJ", "sequence": 1, "type": "webhook"},
"resource_id": "whk_2kP7vR3nXq9LmT4bW8cYzF1dHsJ",
"resource_type": "webhook"
},
"id": "wev_2kP8aQ4kYt6HdS2wR9nMjC5vBxA",
"request_id": "req_4e8a1c7f3b9d42e6a0c5f8b2d7e1a693",
"tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
"type": "webhook.test"
}
id names the event and type says what happened. data.resource.sequence counts the events about the same record, so you can tell which change is newer. request_id appears when an API call caused the change and matches that call in the request log.
Your server has 10 seconds to answer. Redirects are not followed, so a 301 counts as a failure.