Skip to main content
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.

​
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.

What webhooks do

Deliver a signed POST within seconds of the change, retry transient failures with exponential backoff and expose every attempt in a ledger.

What webhooks do NOT do

Carry the resource payload, guarantee ordering, or replace the REST API as the source of truth. A missed delivery never corrupts state.

​
First release scope

​
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

1

Architecture

The two queue stages (webhook-out-route, webhook-out-deliver), the webhook_dispatch ledger and the subscriber-gated publishing rule.
2

Event catalogue

Naming convention, account scope and the generated table of every event.
3

Subscriptions

Creating a webhook, receiving the one-shot secret, choosing events, activating and rotating.
4

Delivery and signature

Headers, body, verification code in Node.js and Python.
5

Retries and failures

Outcome matrix, backoff, exhausted, auto-disable and replay.
6

Operations

Catalogue sync, test deliveries, sink, permissions and known limits.
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.