# Webhooks

Push-based event delivery for partner systems that don't want to poll.
WHost dispatches a signed POST to each registered endpoint when one of
the supported events fires (`account.created`, `account.suspended`,
`license.state_changed`, `webhook.failed`, …).

**Brief flow:**

1. Operator registers an endpoint via `POST /api/v1/webhooks/endpoints`.
2. WHost stores the endpoint with a per-endpoint signing secret.
3. When an audit-logged event occurs, the dispatcher posts to the URL
   with headers `X-WHost-Event`, `X-WHost-Delivery-Id`,
   `X-WHost-Signature`, `X-WHost-Timestamp` and a JSON body.
4. The receiver verifies the signature (use the PHP SDK's
   `WHost\Webhook\WebhookVerifier` or the canonical formula:
   `HMAC-SHA256(secret, "{timestamp}.{body}")`).
5. Non-2xx replies trigger exponential-backoff retries; after the
   final attempt the delivery lands in the dead-letter queue and
   surfaces in `/admin/webhooks → Deliveries → Failed`.

Full event catalog, payload shapes, retry policy and signature
verification recipes — and the **subscriber-side secret rotation
playbook** (no rolling window; two-deploy coordination required) — are
in [`docs/developer/webhooks.md`](webhooks.md).

---