# 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

- [Verify the signature of every delivery](/docs/webhooks/verify)
- [How failed deliveries are retried](/docs/webhooks/retries)
- [Send test events to your receiver](/docs/webhooks/testing)
- [Patterns for a receiver that holds up in production](/docs/webhooks/best-practices)

