@hookdeck/n8n-nodes-hookdeck

Reliable webhooks for n8n. Put the Hookdeck Event Gateway in front of your workflows' inbound webhooks: signature verification for 151 providers, deduplication, a durable queue that survives restarts and unpublished workflows, and retries you can route on from inside the workflow.

Install from n8n's community nodes panel with the package name:

@hookdeck/n8n-nodes-hookdeck

Why

n8n's built-in Webhook trigger hands your provider a URL that leads straight to your instance. A restart, a deploy or an unpublished workflow loses events, a double-firing provider runs the workflow twice, and a failed execution has no event left to retry. The Webhook node cannot tell you any of that happened, because it never saw the event.

This package puts Hookdeck in between and makes its guarantees options on the trigger node:

n8n's Webhook node	With @hookdeck/n8n-nodes-hookdeck
Events lost while n8n is down, deploying, or the workflow is unpublished	Queued durably at Hookdeck. Unpublishing pauses delivery; publishing again delivers everything that arrived in the gap
A delivery n8n did not accept is gone	Retried up to 50 times with exponential or linear backoff, and isLastAttempt on the payload for a dead-letter branch
Provider retries run the workflow twice	Deduplicated at ingest (60 s window by default), plus a stable idempotency key on every delivery
No signature verification unless you build it	Verified at the edge with each platform's own scheme (Stripe, Shopify, GitHub, Twilio and 147 more), or HMAC / API key / basic auth for generic sources. Deliveries into n8n are separately signed
A burst, or one busy tenant, hits n8n at full speed	Delivery rate and concurrency capped upstream, including per-customer limits keyed on a payload path
Debugging means the execution log	Events, attempts, requests and issues inspected, retried and replayed as workflow steps, or in the Hookdeck dashboard

Two nodes do this:

• Hookdeck Event Gateway Trigger starts a workflow when Hookdeck delivers an event. On publish it provisions the Hookdeck connection for you and lists your sources with the public URL to give your provider. Retries, deduplication and rate limits are node options, with no dashboard round-trips.
• Hookdeck Event Gateway manages sources, destinations and connections, and inspects events, delivery attempts, requests and issues. Each operation also works as an AI agent tool.

These nodes cover the Event Gateway only — the inbound path. Outpost, Hookdeck's outbound path for publishing events to your users, is not covered here.

Quickstart

1. Create a Hookdeck account (the free tier is enough) and copy the API key of an Event Gateway project from Project Settings → Secrets.
2. Install @hookdeck/n8n-nodes-hookdeck from Settings → Community Nodes in n8n (guide). n8n Cloud installs only verified community nodes and this package's submission is pending, so for now it runs on self-hosted n8n.
3. Create a Hookdeck Event Gateway API credential and paste the key. One credential is one project.
4. Add a Hookdeck Event Gateway Trigger to a workflow. Under Source → By Name give the source a name, pick the platform sending the events as Source Type, and paste that platform's signing secret into Webhook Secret.
5. Publish the workflow. The node creates the source and the connection to this workflow.
6. Open Source → From List on the node. Each source is listed with its public https://hkdk.events/... URL. Give that URL to Stripe, GitHub, or whatever sends the events.

Events now arrive through Hookdeck with the default rules applied: five exponential retries a minute apart, and a 60 second deduplication window.

If Hookdeck cannot reach your n8n (a laptop, or an instance behind NAT), the node provisions a CLI destination instead and writes the hookdeck listen command to n8n's server log. Install the Hookdeck CLI and run it alongside n8n. Nothing else changes — Transport covers what differs.

Verification only starts when a secret is set. Choosing a Source Type selects which signature scheme applies; it does not enable verification. A STRIPE source with no Webhook Secret accepts unsigned payloads, answers 200, and records verified: false. Security explains how to confirm a source is verifying.

Hookdeck Event Gateway Trigger

Each execution receives one item: the provider's body, headers and query, plus a hookdeck object of delivery metadata that n8n's Webhook node has no way to supply.

{
  "body":    { "...": "the payload the provider sent" },
  "headers": { "...": "all request headers" },
  "query":   { "...": "query string parameters" },
  "hookdeck": {
    "eventId": "evt_...",
    "attemptCount": 1,
    "attemptTrigger": "INITIAL",
    "isLastAttempt": false,
    "idempotencyKey": "evt_...",
    "verified": "true",
    "eventUrl": "https://dashboard.hookdeck.com/events/evt_..."
  }
}

isLastAttempt is true when Hookdeck will not retry again, the condition for a dead-letter branch. idempotencyKey is stable across retries of one event, so it is a sound deduplication key. The trigger reference lists every field.

Hookdeck's connection rules are options on the node:

Option	Default	Purpose
Acknowledgement Mode	Async Retry	Async Retry acknowledges on receipt and runs the workflow after. Sync holds the response until the run finishes, so a failed run answers 5xx and Hookdeck retries the run itself. Sync is capped at 60 seconds
Retry Strategy / Count / Interval	5 exponential retries, 60000 ms	How Hookdeck retries a delivery n8n did not accept. Up to 50 attempts
Deduplication Window (Ms)	60000	Repeat events within the window cost one execution. 0 turns it off
Delivery Rate Limit / Period	none	Cap deliveries per second, minute, hour, or concurrent executions
Delivery Group Key / Rate Limit / Period	none	A rate limit per value of a payload path, so one busy customer cannot crowd out the rest
On Deactivate	Pause	Unpublishing pauses the connection so queued events are held. Delete cancels them
Update Existing Source	off	A source that already exists is adopted as-is. Turn on to apply this node's type and verification to it
Verify Signature	on	Reject deliveries not signed by Hookdeck with 401

The full list, including Header Prefix and Source Config (JSON), is in the trigger reference.

Hookdeck Event Gateway node

Resource	Operations
Attempt	Get, Get Many
Connection	Get, Get Many, Get Count, Delete, Pause, Unpause
Destination	Get, Get Many, Get Count
Event	Get, Get Many, Get Count, Retry, Mute, Cancel
Issue	Get, Get Many, Get Count, Update, Dismiss
Request	Get, Get Many, Retry
Source	Get or Create, Get, Get Many, Get Count, Get URL

Event → Retry is the recovery path for a failed run under Async Retry: add it to the workflow's error branch with {{ $json.hookdeck.eventId }} and Hookdeck redelivers the event. Get Count on events returns a floor (isAtLeast: true) because Hookdeck exposes no event count, which matters when an agent is reading the number. Details in the node reference.

Example workflows

Three importable workflows are in examples/, all built and run against a real n8n instance:

Workflow	Problem it solves
process-each-event-once.json	A retried delivery runs the workflow twice. Gates on hookdeck.idempotencyKey so the second arrival stops before doing the work again
catch-events-on-final-attempt.json	An event that fails every retry disappears silently. Routes on hookdeck.isLastAttempt so the final attempt reaches a dead-letter branch
ai-incident-agent.json	A destination starts failing and retries pile up unnoticed. Hookdeck's own issue.opened notification starts a workflow whose AI Agent reads the issue, counts the failing events and pauses the connection

The dead-letter example mid-run. The first two are not possible with n8n's built-in Webhook node, because both depend on delivery metadata only a gateway can supply. The third is not possible without a gateway at all: the event it reacts to is the gateway reporting a delivery it could not make. examples/README.md describes what was observed running each.

Security model

Webhook payloads are third-party input, and these nodes treat them that way:

• Provider verification happens at the Hookdeck source, using that platform's own scheme, once you supply its signing secret. That secret lives at the Hookdeck source; the trigger sends it there on publish and never checks a signature with it itself.
• Deliveries into n8n carry a second signature, in x-hookdeck-n8n-signature, made with a secret the trigger generates on publish. Requests that fail it get 401 and never start the workflow.
• n8n's own webhook URL is hidden on the trigger. Sending a provider there bypasses Hookdeck and silently loses everything above.
• A body that is not valid UTF-8 is rejected with 400, outside the retryable range, rather than parsed into corrupted text.
• Payload text is data, never instructions. Be careful passing it unfiltered into an AI agent, a shell command or a database write.

Limitations

• Self-hosted n8n only until the verified-node submission lands.
• Sync acknowledgement is capped at 60 seconds. Longer workflows use Async Retry, and recover failed runs with Event → Retry rather than Hookdeck's retry rules.
• The trigger has no completion hook, so deduplication is Hookdeck's Deduplication Window rather than a local ledger. Key on hookdeck.idempotencyKey for a stricter guarantee.
• On the CLI route, a connection with no hookdeck listen session records no event at all, and Delivery Rate Limit and Delivery Group are unavailable.
• n8n 1.x is untested.

Limitations has each in full.

Documentation

The README covers the common path. Everything else lives in docs/:

Guide	What's in it
Getting started	Install, credentials, setting up the trigger, finding the source URL, and what has been verified end to end
Trigger reference	Every parameter and option, acknowledgement modes, the full output, and what publish, unpublish and test runs do
Transport	The direct and CLI delivery routes, running hookdeck listen, and what the CLI route cannot do
Security	The two signatures, why a typed source is not a verified one, and malformed bodies
Action node	Every resource and operation, Get or Create, counts, retry versus replay, and use as an agent tool
Limitations	Known boundaries, and where this node departs from the shared reliability contract
Example workflows	What each example does and what was observed running it

Development

npm test               # build + unit tests, no n8n or Hookdeck account required
npm run scan           # the rules n8n runs for verification
npm run lint
npm run test:live      # creates and deletes real Hookdeck resources (needs HOOKDECK_EG_API_KEY)

Trying the nodes in a real n8n, the pre-PR checklist and releasing are in CONTRIBUTING.md.

Learn more

• Hookdeck docs and API reference
• n8n community nodes
• Hookdeck Console: inspect webhooks without an account

Issues and PRs welcome. MIT.