---
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](https://hookdeck.com/docs/sources)** (ingestion endpoint with a unique `https://hkdk.events/xxx` URL) connects to a **[Destination](https://hookdeck.com/docs/destinations)** (your endpoint) via a **[Connection](https://hookdeck.com/docs/connections)** that can have [Rules](https://hookdeck.com/docs/connections) (filter, transform, retry, delay, deduplicate).

## Documentation

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

## Use Cases

| Use case | When to use | Quickstart |
|----------|-------------|------------|
| **Receive webhooks** | Ingesting third-party webhooks (Stripe, Shopify, GitHub, etc.) | [quickstart](https://hookdeck.com/docs/use-cases/receive-webhooks/quickstart) |
| **Third-party routing** | Routing events between services (Zapier-like integration flows) | [quickstart](https://hookdeck.com/docs/use-cases/third-party-routing/quickstart) |
| **Asynchronous APIs** | Event ingestion at scale from IoT devices, SDKs, web analytics | [quickstart](https://hookdeck.com/docs/use-cases/asynchronous-apis/quickstart) |
| **Test & debug localhost** | Local webhook development with the CLI | [quickstart](https://hookdeck.com/docs/use-cases/test-debug-localhost/quickstart) |

> **Sending webhooks to customers?** Use [Outpost](https://github.com/hookdeck/agent-skills/blob/main/skills/outpost/SKILL.md) 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](https://github.com/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](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](references/verification-code.md)).
2. **The provider skill** — Try installing first: `npx skills add hookdeck/webhook-skills --skill {provider}-webhooks` (e.g. `stripe-webhooks`, `shopify-webhooks`). If install succeeds, use the installed skill; if it fails, the provider may not be in webhook-skills — look up the [repo](https://github.com/hookdeck/webhook-skills) 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`."

**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](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/express/), [examples/nextjs/](examples/nextjs/), [examples/fastapi/](examples/fastapi/).
- Do not use third-party webhook libraries; use only the verification code from this skill.

## Workflow Stages

Follow these in order for a new Hookdeck integration:

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

Stage 02: when the user is working with a provider (Stripe, Shopify, etc.), complete [references/provider-webhooks-checklist.md](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` with `--path`, Source URL for provider).

## Quick Start (Receive Webhooks)

No account required -- `hookdeck listen` works immediately:

```sh
brew install hookdeck/hookdeck/hookdeck   # or: npm i -g hookdeck-cli
hookdeck listen 3000 --path /webhooks
```

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

```sh
hookdeck login
hookdeck listen 3000 --path /webhooks
```

The CLI creates a Source URL, a Destination pointing at `localhost:3000`, and a Connection linking them. 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`).

**Production:** Two options. **(1) Same project:** Keep the same project and connections; update the [Destination](https://hookdeck.com/docs/destinations) to your production HTTPS endpoint (e.g. `https://api.example.com/webhooks`) via the [Dashboard](https://dashboard.hookdeck.com) or [API](https://hookdeck.com/docs/api). **(2) New project:** Create a [new project](https://hookdeck.com/docs/projects) in Hookdeck and duplicate your setup (Sources, Connections) with Destinations pointing to your 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, consider: **rate limiting / max delivery rate** ([Destinations](https://hookdeck.com/docs/destinations)), **configuring retries** ([Retries](https://hookdeck.com/docs/retries)), and **issue notifications** ([Issue triggers](https://hookdeck.com/docs/issue-triggers), [Issues & Notifications](https://hookdeck.com/docs/issues)). Hookdeck docs are the source of truth; see [Receive webhooks quickstart — Deliver to production](https://hookdeck.com/docs/use-cases/receive-webhooks/quickstart#deliver-to-your-production-webhook-endpoint) and the linked Destinations, Retries, and Issue triggers docs for the full production checklist.

## Reference Material

Use as needed (not sequential):

### Setup & Terminology

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

### Configuration

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

### Development & Operations

| Area | Resource | When to use |
|------|----------|-------------|
| CLI | [references/cli-workflows.md](references/cli-workflows.md) | CLI installation, connection management, project switching |
| API | [references/api-patterns.md](references/api-patterns.md) | REST API automation, bulk operations, publish |
| Monitoring | [references/monitoring-debugging.md](references/monitoring-debugging.md) | Failed deliveries, event lifecycle, troubleshooting |

### Verification Code

| Area | Resource | When to use |
|------|----------|-------------|
| Code | [references/verification-code.md](references/verification-code.md) | Hookdeck signature verification (Express, Next.js, FastAPI) |
| **Provider webhooks** | [references/provider-webhooks-checklist.md](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/express/), [examples/nextjs/](examples/nextjs/), [examples/fastapi/](examples/fastapi/) | Runnable, proven, tested verification handlers — use these as the reference implementation for the user's framework |