> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bbrands.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Outbound webhooks

> How horizon-api notifies external systems when a resource changes: signed HTTPS deliveries, a generated event catalogue, per-account or global subscriptions, retries and operator tooling.

<Info>
  This section documents the **outbound webhook layer** of `horizon-api`.
  Every mutating v3 route publishes a catalogue event; subscribers registered
  through the Webhook module receive a signed `POST` for the events they
  chose. For the inbound direction (third parties calling us, e.g. payment
  providers) see the integration-specific sections.
</Info>

## What this is

A webhook is an HTTPS endpoint you own. When a resource you care about is
created, updated, activated or deleted, `horizon-api` sends a **thin, signed
notification** to that endpoint. The body identifies *what* changed
(`event`, `data.document_id`, `data.account`), not the full resource: your
system then reads the current state through the REST API with its own
credentials.

<CardGroup cols={2}>
  <Card title="What webhooks do" icon="bell">
    Deliver a signed `POST` within seconds of the change, retry transient
    failures with exponential backoff and expose every attempt in a ledger.
  </Card>

  <Card title="What webhooks do NOT do" icon="circle-xmark">
    Carry the resource payload, guarantee ordering, or replace the REST API
    as the source of truth. A missed delivery never corrupts state.
  </Card>
</CardGroup>

## First release scope

| Capability                                                             | Status                                          |
| ---------------------------------------------------------------------- | ----------------------------------------------- |
| Catalogue generated from the v3 route tree (`<resource>.<action>`)     | Available                                       |
| Global subscriptions (`is_global: true`) and per-account subscriptions | Available                                       |
| HMAC-SHA256 signature with timestamp (`x-bbrands-signature`)           | Available                                       |
| Retries `1 m → 5 m → 30 m → 2 h → 6 h`, then `exhausted`               | Available                                       |
| Automatic disable after 20 consecutive failed deliveries               | Available                                       |
| Operator replay, test delivery, secret rotation                        | Available                                       |
| Dashboard summary and catalogue status endpoints                       | Available                                       |
| Resource payload inside the body                                       | Not planned — read the resource through the API |
| Fixed egress IP for allow-listing                                      | Not available in this release                   |

## Requirements for a subscriber endpoint

* **HTTPS only.** Plain `http://` URLs are rejected except in the local
  `development` environment.
* **Publicly reachable host.** Loopback, link-local, private ranges (IPv4 and
  IPv6), cloud metadata addresses and `*.internal` names are refused when the
  webhook is created or updated.
* **No redirects.** The delivery worker never follows `3xx`; a redirect is a
  terminal error for that attempt.
* **Answer `2xx` within 10 seconds.** Do the real work asynchronously.
* **Verify the signature** before trusting the body and **deduplicate on the
  delivery id**, because retries and replays reuse it.

## How to read this section

<Steps>
  <Step title="Architecture">
    The two queue stages (`webhook-out-route`, `webhook-out-deliver`), the
    `webhook_dispatch` ledger and the subscriber-gated publishing rule.
  </Step>

  <Step title="Event catalogue">
    Naming convention, account scope and the generated table of every event.
  </Step>

  <Step title="Subscriptions">
    Creating a webhook, receiving the one-shot secret, choosing events,
    activating and rotating.
  </Step>

  <Step title="Delivery and signature">
    Headers, body, verification code in Node.js and Python.
  </Step>

  <Step title="Retries and failures">
    Outcome matrix, backoff, `exhausted`, auto-disable and replay.
  </Step>

  <Step title="Operations">
    Catalogue sync, test deliveries, sink, permissions and known limits.
  </Step>
</Steps>

<Note>
  Managing webhooks (create, subscribe, rotate, replay) requires the
  `administrator` role in Horizon Enterprise or the equivalent `webhook:*`
  permissions on an API token. See the [API reference](/api-reference/webhook/webhook/find-all).
</Note>