Platform 3 of 12·OS Layer 8 (Event Layer)·Required in all deployment modes

Scope of this page. Reference material for the Hookdeck platform: what it is, what it is normally used for, and how and why Synedrix OS uses it. It is descriptive, not normative — where this page and a canonical spec in docs/os/ disagree, the canonical spec wins. Platform responsibilities are set by Tech Stack §2; the event contract Hookdeck delivers against is the Event Taxonomy Standard.

This page covers inbound only. Hookdeck (the Event Gateway) and Hookdeck Outpost (outbound delivery) are separate products with separate licences and separate deployment stories. Outpost is covered on its own page: Hookdeck Outpost — Egress Gateway.

What Hookdeck is

Hookdeck describes itself as providing “reliable infrastructure to work with webhooks and external events — without managing it yourself.” The inbound product is the Event Gateway, which “enables you to manage inbound webhooks and events before they hit your app, including receiving, transforming, and routing events, with full observability and control.”

Architecturally it is a proxy and a queue: “Hookdeck acts as an HTTP proxy and queue between the webhook producer and your application.” An inbound HTTP call becomes a request; a request matched to a connection becomes an event; each delivery of that event is an attempt.

ConceptOfficial definition
Source“A source is a representation of a service that sends HTTP requests to the Hookdeck Event Gateway.”
Destination“A destination is any endpoint to which your events can be routed.”
Connection“A connection lets you route events from a Source to a Destination.”
Request“Requests are HTTP requests that Hookdeck receives from a source.”
Event“An event is created when a request is associated with a connection. The event moves through the connection’s rules pipeline (filters, transformations, deduplication) and, if it passes all rules, is queued for delivery.”
AttemptAn “attempt is a specific delivery attempt that Hookdeck makes for a queued event.”
Filter“Filters allow you to permit and route events conditionally based on the contents of their Headers, Body, Query, or Path.”
Transformation“A transformation lets you modify the payload of a event prior to delivery.”
Deduplication“Deduplication removes redundant events by comparing them against previously processed events within a configurable time window.”
Retry“Webhook retries are automatic re-attempts to deliver an event after a failed delivery.”
Bookmark“A bookmark lets you conveniently store and replay a specific request.”
Issue“Issues let you track problems in your project and communicate resolution steps with your team.”

The details that matter for a governed system:

  • Delivery guarantee. “Hookdeck operates on an ‘at least once’ delivery guarantee, meaning an Event may be delivered more than once.” Ordering is explicitly not guaranteed: “There’s no guarantee of the order in which Events will arrive.” Hookdeck’s own advice is to use payload data such as an updated_at value to reconcile out-of-order arrival.
  • Buffering. “If your destination is unreachable, events are held in the queue and delivered when your server recovers.”
  • Retries. Automatic retries use a linear or exponential strategy — “with a linear strategy, retries occur at regular intervals; with an exponential strategy, each retry is delayed twice as long as the previous.” “Events are limited to 50 automatic retries, but can be manually retried as many times as you like.” A failed event “remains stored in Hookdeck and can be manually retried or bulk retried at any time after the underlying problem is resolved.”
  • Replay. Bookmarks are the replay primitive, and the semantics are worth reading twice: “Contrary to an event retry, triggering a bookmark creates a new event instead of a new attempt.”
  • Filters discard. Events not matching a filter “are disregarded by Hookdeck and recorded as ignored events” and “will not appear in your list of events or generate delivery attempts.”
  • Transformations are sandboxed. They run as JavaScript (ES6) in a V8 isolate, capped at 1 second of execution and 5 MB, with no network or filesystem I/O and no async/await.
  • Source authentication. Sources support HMAC (configurable algorithm and encoding), Basic Auth, API keys and generic schemes, with pre-configured settings for known providers; secrets are AES encrypted. Sources ingest requests up to 10 MiB and support custom domains.
  • Delivery rate. “Setting a delivery rate allows you to define a maximum rate at which Hookdeck will send delivery attempts to a destination” — per second, per minute, per hour, or a concurrency cap. Excess events queue as Pending.
  • Observability. “Every request, event, and delivery attempt is logged with full headers, payloads, and response data,” with metrics and issue notifications to email, webhook, Slack, Discord, Microsoft Teams, PagerDuty, OpsGenie, Better Stack Uptime and incident.io.

Configuration surfaces are the dashboard, the REST API, the CLI, an MCP server, and an official Terraform provider — the last of which is the supported path for version-controlling connections, filters and transformations.

What Hookdeck is normally used for

The use cases Hookdeck’s own documentation leads with:

  • Receiving webhooks — putting a durable queue in front of an application so that provider retries, bursts and downstream outages do not lose events.
  • Localhost testing — the CLI’s hookdeck listen forwards inbound events to http://localhost:$PORT/$DESTINATION_PATH so a developer can debug against real provider traffic.
  • Third-party routing — fanning one inbound source out to many destinations, each with its own filters, transformations and retry policy.
  • Async APIs — accepting an HTTP call at the edge, acknowledging immediately, and letting the queue absorb the processing.

The common thread is that Hookdeck owns arrival: authenticating the caller, absorbing the burst, deciding what is a duplicate, and holding the event until something downstream is ready for it — not what the event means.

How Synedrix OS uses it

Hookdeck is the ingress gateway of Synedrix OS and sits at Layer 8 (Event Layer) of the twelve-layer taxonomy, alongside Hookdeck Outpost on the egress side. Per Tech Stack it is required in all three deployment modes, with an external write access pattern and a sub-second latency profile.

flowchart LR
  n1([Hookdeck]):::term
  subgraph What it owns
    n2[Inbound event validation]:::agent
    n3[Schema enforcement]:::agent
    n4[Buffering]:::agent
    n5[Replay]:::agent
    n6[Fan-out]:::agent
  end
  n1 --> n2
  subgraph What it does not own
    n7[Outbound and callback delivery to external systems]:::warn
    n8[Hookdeck Outpost]:::term
    n7 --> n8
    n9[Canonical business state]:::warn
    n10[Supabase PG17]:::term
    n9 --> n10
    n11[Lineage graph and audit trail]:::warn
    n12[Neo4j]:::term
    n11 --> n12
  end
  n1 --> n7
  subgraph Why Hookdeck
    n13[Replay is a first-class primitive]:::term
    n14[Fan-out is configuration not code]:::term
    n15[It is declarable]:::term
  end
  n1 --> n13

What it owns

Per Tech Stack §2, Hookdeck owns:

  • Inbound event validation
  • Schema enforcement
  • Buffering
  • Replay
  • Fan-out

In contract terms, Hookdeck is the platform that satisfies trigger_source for every workflow declared with trigger_type: event under the Workflow Contract Spec. It is the boundary at which an untrusted external HTTP call becomes a candidate Synedrix OS event, and the buffer that decouples a provider’s retry behaviour from n8n’s availability.

What it does not own

ConcernOwner
Outbound and callback delivery to external systemsHookdeck Outpost (Layer 8, egress)
The event envelope, naming rules and lifecycle rulesEvent Taxonomy Standard
Workflow sequencing, retries of business steps, approval routingn8n (Layer 3)
Policy decisions on whether an event may cause a side effectPolicy Guard (os-agt-002, Layer 9)
Canonical business stateSupabase PG17 (Layer 7)
Lineage graph and audit trailNeo4j (Layer 7) and the Layer 10 observability platforms

Three boundaries worth stating explicitly

Envelope compliance is an OS responsibility, not a Hookdeck feature. Hookdeck validates transport — signature, auth, payload size, content type — and can shape a payload with a transformation. It does not know about the fifteen-field envelope. The Event Taxonomy Standard requires that “an event that omits any required field is non-compliant and must be rejected by the event layer,” and requires correlation_id and causation_id on every event. An inbound provider webhook carries neither. Envelope construction — minting event_id, assigning domain, entity_type, source_type: external_system, and either propagating an inbound correlation_id or minting one at the boundary — must happen deliberately, either in a Hookdeck transformation or in the first n8n node. Whichever is chosen, it should be chosen once and applied uniformly; envelope assembly split across both is how lineage gaps start.

Filters silently discard. Non-matching events are “recorded as ignored events” and generate no delivery attempts. That is a legitimate ingress optimisation and a lineage hazard: an event dropped at Layer 8 never reaches Neo4j, QuestDB or the audit trail. Filters should be used for genuine noise (irrelevant provider event types), not for anything a reviewer might later need to account for. Anything that resembles a policy decision belongs at Layer 9, behind governance, not in an ingress filter.

Deduplication overlaps with Redis. Hookdeck’s deduplication window is configurable between one second and one hour. Redis at Layer 7 owns idempotency keys and deduplication windows for the OS. These are two deduplication mechanisms at two layers with different retention and different visibility, and the idempotency_strategy field of the workflow contract must name which one a given workflow relies on. Collapsing both onto “it is deduplicated somewhere” is how at-least-once delivery turns into duplicate side effects.

At-least-once is the design constraint

Hookdeck guarantees at-least-once delivery and no ordering. Both are load-bearing for anything downstream that writes:

  • Every event-triggered workflow needs a real idempotency_strategy, not an assumption of exactly-once arrival.
  • Ordering must be reconstructed from payload data or from causation_id, never from arrival sequence.
  • Replay via a bookmark creates a new event, not a retry — so a replayed inbound request produces a second event_id, and correlation must be handled explicitly rather than inferred.

Why Hookdeck

  • It moves ingress failure out of the orchestration layer. Provider webhooks arrive whether or not n8n is up. A queue at the edge means an n8n restart is a delay, not a data-loss event — which is what Layer 8’s decoupling role exists for.
  • Replay is a first-class primitive. A governed system needs to be able to re-run an inbound signal against a corrected workflow. Bookmarks make that an operation rather than a reconstruction exercise.
  • Signature verification happens before the OS trusts anything. HMAC and provider-specific verification at the source means n8n never sees an unauthenticated external payload, which is the precondition for treating an inbound event as a governed trigger at all.
  • Fan-out is configuration, not code. One source to many connections, each with its own filters and retry policy, keeps ingress routing out of workflow logic.
  • It is declarable. The Terraform provider and API mean connections, filters and transformations can live in version control alongside the specs that describe them.

The counterweight to all of this is in the next section, and it is significant.

Deployment and licensing

Managed cloud. The Hookdeck Event Gateway is a hosted service. Plans are Developer (free), Team, Growth and Enterprise. Configuration is via dashboard, API, CLI, MCP server or the Terraform provider.

Self-hosting — this does not exist for the Event Gateway. Hookdeck’s public documentation, pricing page and product site describe no self-hosted, on-premise or private-cloud deployment of the Event Gateway. Hookdeck’s self-hosting documentation lives entirely under the Outpost namespace (/docs/outpost/self-hosting/), and Hookdeck’s public GitHub organisation contains the CLI, SDKs, the Terraform provider and Outpost — but no Event Gateway server. The Event Gateway source is not published.

The CLI is not an offline mode. hookdeck listen forwards events to localhost, but it does so by tunnelling through Hookdeck’s cloud. It is a development convenience, not a local deployment of the gateway.

Licence. The Event Gateway is proprietary and closed-source. Outpost, by contrast, is Apache 2.0 and genuinely self-hostable — the two products are frequently conflated because they share a vendor and a docs site, but their licensing and deployment characteristics are not the same. See Hookdeck Outpost — Egress Gateway.

Mode 3 is the hard problem

Deployment Model Spec defines Mode 3 (air-gapped) as: “No external API calls of any kind. No data leaves the customer’s infrastructure under any circumstances,” with “Zero external connections permitted” and network egress rules configured to block all outbound traffic.

A managed cloud Event Gateway cannot exist inside that definition. In Mode 3, every inbound event would have to traverse Hookdeck’s infrastructure before reaching the customer’s network — meaning external data flow, an inbound hole in the perimeter, and third-party custody of payloads that Mode 3 exists specifically to prevent. Marking Hookdeck as required “in all modes” and marking Mode 3 as permitting zero external connections cannot both be true.

Four options were considered. This page does not choose between them; the decision-maker did, in ADR-OS-013 (rejected), selecting the last:

OptionConsequence
Restrict Hookdeck to Modes 1 and 2Mode 3 needs a different Layer 8 ingress implementation, and “required in all modes” must be corrected in Tech Stack and Deployment Model Spec.
Define a Mode 3 ingress substituteA self-hostable queue plus signature verification in front of n8n. Loses replay, issue tracking and the managed retry pipeline; those capabilities would need owners.
Pursue an Enterprise arrangementHookdeck’s Enterprise tier is custom-priced and undocumented publicly; whether any on-premise arrangement exists is unknown from official sources and would need to be established directly with the vendor.
Accept the exception explicitlyRecord Hookdeck as a documented deviation from Principle 11 and from the Mode 3 zero-egress rule. Honest, but it changes what “air-gapped” means in a sales conversation.

Decision. The last option was chosen: Hookdeck stays required in all modes and the deviation is accepted. “Hookdeck, all modes” is therefore a settled specification, with Mode 3 carrying one declared external dependency — the inbound Hookdeck path. The Deployment Model Spec §1 states what that means for an air-gapped instance, including who it is not suitable for. The Enterprise option above remains available as a commercial convenience, not a requirement.

Official documentation

Synedrix OS · Platform reference · Hookdeck