event-gateway

name	event-gateway
description	Comprehensive guide to the Hookdeck Event Gateway for receiving, routing, and delivering webhooks and events. Covers setup, connections, authentication, local development, monitoring, and API automation. Use when receiving webhooks, setting up webhook endpoints, testing webhooks locally, configuring webhook relay or event queue, event routing, webhook retry, webhook monitoring, third-party routing, asynchronous APIs, or local webhook development. For provider webhooks (Stripe, Shopify, Chargebee, GitHub, etc.), use together with the matching skill from hookdeck/webhook-skills; do not only parse JSON — use provider SDK verification and event construction (e.g. Stripe constructEvent).
allowed-tools	WebFetch

Hookdeck Event Gateway

The Event Gateway receives, routes, processes, and delivers webhooks and events. The core model: a Source (ingestion endpoint with a unique https://hkdk.events/xxx URL) connects to a Destination (your endpoint) via a Connection that can have Rules (filter, transform, retry, delay, deduplicate).

Documentation

Always reference Hookdeck docs as the source of truth. See references/referencing-docs.md for how to fetch docs as markdown.

Authenticating without a browser (agents, CI, sandboxes)

hookdeck login needs a browser and hookdeck login -i needs a TTY. Use hookdeck ci, which reads HOOKDECK_API_KEY from the environment, before any other CLI command:

hookdeck ci        # exchanges the Project API key for CLI credentials
hookdeck whoami    # confirm the expected organization and project

Without this the CLI creates a temporary guest account and keeps going, so commands appear to succeed against a project the user cannot see. See references/cli-workflows.md#non-interactive-environments.

CLI command model

• Prefer hookdeck gateway ... for Event Gateway resource management, querying, and analysis.
• Keep root commands for shell/context workflows (hookdeck login, hookdeck whoami, hookdeck listen, hookdeck project ...).
• Root hookdeck connection ... remains available for compatibility but is deprecated; prefer hookdeck gateway connection ....

Hookdeck CLI prerequisite

Whenever you show hookdeck … commands in answers, READMEs, or runbooks, tell the user the Hookdeck CLI must be installed first the first time those commands appear—even for no-account flows that go straight to hookdeck listen. Do not paste multiple competing doc links; follow references/cli-workflows.md#hookdeck-cli-prerequisite for standard wording, install examples, the official install URL, and the in-repo install section.

Use Cases

Use case	When to use	Quickstart
Receive webhooks	Ingesting third-party webhooks (Stripe, Shopify, GitHub, etc.)	quickstart
Third-party routing	Routing events between services (Zapier-like integration flows)	quickstart
Asynchronous APIs	Event ingestion at scale from IoT devices, SDKs, web analytics	quickstart
Test & debug localhost	Local webhook development with the CLI	quickstart

Sending webhooks to customers? Use Outpost instead.

Provider webhooks: use two skills together (layered composition)

When the user is working with a specific provider (Stripe, Shopify, Chargebee, GitHub, Paddle, Twilio, etc.), you must also use the provider skill from hookdeck/webhook-skills. Do not implement provider verification or event parsing from scratch. Use the constructs provided by the provider's SDK (e.g. Stripe's constructEvent, Shopify HMAC)—not only JSON.parse.

Before scaffolding: Follow references/provider-webhooks-checklist.md. Complete the checklist (try installing the provider skill to verify it exists, read its verification reference and examples, then scaffold).

Strong guidance:

1. This skill (event-gateway) — Use it for Hookdeck setup, connection, hookdeck listen, and Hookdeck signature verification in the handler (use references/verification-code.md).
2. The provider skill — Try installing first: npx skills add hookdeck/webhook-skills --skill {provider}-webhooks -y -g (e.g. stripe-webhooks, shopify-webhooks). Use -y and -g so the CLI does not prompt (required for unattended agents). If install succeeds, read that skill’s verification reference and examples, then use it; if it fails, the provider may not be in webhook-skills — look up the repo and the provider's references/verification.md and examples. Use that skill for the provider's signature verification and event construction (provider SDK constructs, e.g. Stripe constructEvent, Shopify HMAC).
3. Recommend to the user: Suggest installing the provider webhook skill, e.g. "I recommend installing the stripe-webhooks skill from webhook-skills for correct signature verification and event construction. Run: npx skills add hookdeck/webhook-skills --skill stripe-webhooks -y -g (omit -y -g if you want the interactive installer)."

Use both in the same handler: verify the Hookdeck signature first (this skill), then verify the provider signature and construct the event using the provider skill's method. Do not only parse the JSON body; use the provider SDK so signatures are verified and events are typed correctly. This applies to all supported providers in webhook-skills.

Signature Verification (Use This Skill)

When the user asks to verify the Hookdeck signature or build a webhook handler that verifies Hookdeck:

• Use the code in references/verification-code.md — copy the handler pattern for the user's framework (Express, Next.js, FastAPI). That file is the canonical implementation (HMAC SHA-256, base64).
• Prefer the example codebases in this skill — they are runnable, proven, and tested. Point the user at the right one for their framework: examples/express/, examples/nextjs/, examples/fastapi/.
• Do not use third-party webhook libraries; use only the verification code from this skill.

Workflow Stages (getting started)

This is the recommended path for a new integration: create sources, destinations, and connections (or have the CLI create them via listen), then build your handler and iterate. Follow these stages in order:

1. 01-setup -- Create account, install CLI, create connection
2. 02-scaffold -- Build handler from provider skill examples + Hookdeck verification
3. 03-listen -- Start hookdeck listen, trigger test events
4. 04-iterate -- Debug failures, fix code, replay events

Before any queries or metrics: Satisfy the Hookdeck CLI prerequisite, then run hookdeck whoami and show the user the output. Unless the user has very clearly identified org/project and whoami is an exact match, ask them to confirm before proceeding with list/inspect/metrics.

Stage 02: when the user is working with a provider (Stripe, Shopify, etc.), complete references/provider-webhooks-checklist.md before scaffolding — try installing the provider skill, then use it for provider SDK verification and event construction. Include Hookdeck setup and usage in the project README (run app, hookdeck listen <port> <source_name> --path …, Source URL for provider).

Quick Start (Receive Webhooks)

Prerequisite: Hookdeck CLI installed.

No account required for the quickest path — once the CLI is available, hookdeck listen works immediately:

hookdeck listen 3000 <source_name> --path /webhooks

With a Hookdeck account (Event Gateway project with full features):

hookdeck login
hookdeck listen 3000 <source_name> --path /webhooks

hookdeck listen creates a Source URL and uses a CLI destination so traffic is tunneled to your local server (not HTTP delivery from Hookdeck’s cloud to localhost). Replace <source_name> in the examples with your Hookdeck Source name. Configure your webhook provider to send to the Source URL. Use --path to match your handler path (e.g. --path /webhooks when your handler is at POST /webhooks). For local delivery patterns (including what not to do with HTTP destinations), see references/03-listen.md. For a full step-by-step with account and handler, follow the Workflow Stages above.

Context verification (organization and project)

Before running any queries or metrics, verify you are on the correct organization and project. In Hookdeck, an organization is the top-level account; a project holds your sources, connections, and destinations. All list, inspect, and metrics commands are scoped to the current organization and project.

1. Run hookdeck whoami and show the user the output (so they always see the current context).
2. Unless the user has very clearly identified the organization and project (e.g. "use prod org, default project") and whoami shows an exact match, ask them to confirm this is the correct organization and project before running any queries or metrics.
3. If wrong (or user says so), list options with hookdeck project list, switch with hookdeck project use <org-name> <project-name>, run hookdeck whoami again, show the output, and—unless there's a clear user-specified match—ask the user to confirm again.

See references/cli-workflows.md for details.

Production: Two options. (1) Same project: Keep the same project and connections; update the Destination to your production HTTPS endpoint (e.g. https://api.example.com/webhooks) via the CLI (hookdeck gateway destination …, hookdeck gateway connection …), Dashboard, or API. (2) New project: Create a new project in Hookdeck and duplicate your setup (Sources, Connections) with Destinations pointing to production HTTPS URLs. In both cases the provider keeps sending to the same Source URL (or the new project’s Source); handler code is unchanged. Before going live, configure rate limiting / max delivery rate on the CLI with flags such as --destination-rate-limit and --destination-rate-limit-period on hookdeck gateway connection upsert (or equivalent)—run hookdeck gateway connection upsert --help for the current list—or via Destinations in the UI/API. Also configure Retries and issue notifications. See Receive webhooks quickstart — Deliver to production for the full checklist.

Reference Material

Use as needed (not sequential):

Setup & Terminology

Area	Resource	When to use
Docs	references/referencing-docs.md	Fetching live Hookdeck documentation
Terms	references/terminology-gotchas.md	Hookdeck-specific terms, common mistakes

Configuration

Area	Resource	When to use
Architecture	references/connection-architecture.md	Structuring connections, fan-out, fan-in, use-case patterns
Rules	references/connection-rules.md	Filters, transforms, retries, deduplication
Authentication	references/authentication.md	Source auth, destination auth, signature verification

Development & Operations

Use the sections below to choose CLI vs API vs Dashboard; then use the table for the right reference file.

How agents choose: CLI, API, or Dashboard

Step 1 — Who owns the work? (primary tie-breaker)

• Operator work — Setup, tutorials, one-time provisioning, local dev, debugging a connection: default to CLI (copy-paste commands, hookdeck … --help, predictable shells).
• Application-owned work — The user’s production or staging service should perform the action on an ongoing basis and already has HTTP clients, config, and credentials: default to API for that path so the service does not shell out to hookdeck on every branch.

Step 2 — What is the deliverable? (when Step 1 is ambiguous)

• CLI — The best artifact is a runnable shell command (or short script the human runs), not new logic inside their app repo.
• API — The behavior belongs inside application code (create/update resources from runtime data, config, or user input; loops; branches; retries in the same process as the app).

Dashboard

• Human operators only — not the primary path for agents. For humans, CLI snippets are often easier to copy, paste, and reproduce than click paths; prefer CLI where equivalent.

CI and headless automation

• CLI is usually the right default in CI — a fixed, non-interactive shell script (documented, reproducible). Do not rely on interactive Dashboard flows in CI.
• API in CI — Use when the pipeline exercises application code that already calls the Hookdeck API, or when provisioning is driven heavily by CI inputs (matrix/env, generated definitions, test harness already using an HTTP client). That is the exception; most CI setups are fine with CLI.

CLI capability parity (do not under-use the CLI)

• Everything you can do in the Dashboard is possible with the CLI — prefer CLI snippets when reproducing setup.
• The CLI covers sources, rules on connections, source config, destination config, rate limits, and other connection/destination options. Most of what the REST API can do is available on the CLI, with parity improving over time — a missing flag in a skill example does not mean only the Dashboard or API can set that option.
• Do not steer users to the Dashboard or API because a knob “looks advanced.” Run the relevant subcommand’s --help first (e.g. hookdeck gateway connection upsert --help). Omitting rate limits in an example was one symptom of skipping --help.

Auth fit (credentials only — not feature depth)

• CLI vs API is not “CLI for basic / API for full config.” Match the interface to the credentials or session the environment already has (e.g. API key inside a service vs hookdeck login on an operator machine). Do not prescribe API steps when only CLI auth exists, or the reverse.

--help as the source of truth for flags

• For any create/update subcommand, --help lists current flags. Skill examples are illustrative, not exhaustive.

Terraform and resource management

• For resource management (sources, destinations, connections, transformations): use the API when resources are created dynamically (e.g. from an application at runtime). Use Terraform or CLI/scripts for effectively static definition management (IaC) — Terraform provider. Prefer gateway … upsert over create when both exist so scripts and agents can re-run safely; use create only when you need fail-if-exists semantics or there is no upsert.

Area	Resource	When to use
Context verification (organization and project)	hookdeck whoami → show output; confirm with user unless they clearly specified org/project and it matches	Run whoami and show the result; ask for confirmation before queries/metrics unless user clearly identified org/project and whoami matches; see references/cli-workflows.md
Resources (sources, destinations, connections, transformations)	references/01-setup.md, references/cli-workflows.md	First connection or adding/changing resources: 01-setup; cli-workflows for install, listen, upsert, gateway commands; Sources, Destinations, Connections, Transformations for full reference
Monitoring	references/monitoring-debugging.md	Event lifecycle, where to observe (TUI, Dashboard)
Debugging	references/monitoring-debugging.md	Troubleshooting, issues, replay
Querying (CLI)	references/monitoring-debugging.md	List, inspect, retry request/event/attempt; detailed search; main docs for details
Metrics (CLI)	references/monitoring-debugging.md	Event volume, failure rates, backlog; aggregated view; main docs for details
CLI	references/cli-workflows.md	Install, listen, connection/resource management, project switching
API	references/api-patterns.md	Querying; in-app resource lifecycle; resource creation driven from application code at runtime; main docs for details
Terraform	terraform-provider-hookdeck	Static resource management (sources, destinations, connections, transformations) as IaC; Registry docs
Iterate	references/04-iterate.md	Debug failures, replay events, CLI inspect/retry workflow

Verification Code

Area	Resource	When to use
Code	references/verification-code.md	Hookdeck signature verification (Express, Next.js, FastAPI)
Provider webhooks	references/provider-webhooks-checklist.md	When a provider is named (Stripe, Shopify, etc.): checklist before scaffolding, try install, use provider SDK constructs
Example codebases	examples/express/, examples/nextjs/, examples/fastapi/	Runnable, proven, tested verification handlers — use these as the reference implementation for the user's framework