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.

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

json
{
  "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:

json
{
  "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.

Next steps#