From ca1544e0aa14850bc476f2541253e41e54594130 Mon Sep 17 00:00:00 2001 From: Phil Leggetter Date: Thu, 26 Feb 2026 20:22:37 +0000 Subject: [PATCH 1/4] docs: align skills with AGENTS.md guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AGENTS.md: - Clarify ref→ref: one-hop for workflow/see-also OK; avoid long chains - Shorten commands/options guidance; add checklist item for capability summaries + link to canonical reference - Add spec checklist item for ref→ref rule event-gateway: - SKILL: Workflow Stages (getting started), Quick Start→Stages link, Resources row (sources, destinations, connections, transformations) - monitoring-debugging: drop api-patterns ref→ref; CLI links use .md URLs; add metrics to Documentation list - cli-workflows: CLI doc links use .md URLs; note per-command as Markdown - connection-rules: bulk replay → live API docs (Bulk, Inspect) - 04-iterate: API patterns → live API docs; keep referencing-docs link Made-with: Cursor --- AGENTS.md | 16 +- skills/event-gateway/SKILL.md | 19 ++- skills/event-gateway/references/04-iterate.md | 2 +- .../event-gateway/references/cli-workflows.md | 12 +- .../references/connection-rules.md | 2 +- .../references/monitoring-debugging.md | 161 +++++++++--------- 6 files changed, 117 insertions(+), 95 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4a4e77b..b72f9a4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,7 +15,7 @@ All skills MUST conform to the [Agent Skills specification](https://agentskills. - `name`: max 64 chars, lowercase `a-z`, numbers, and hyphens only. Must match the parent directory name exactly. No consecutive hyphens. Cannot start or end with a hyphen. - `description`: max 1024 chars. Third person. Describes what the skill does AND when to use it with specific trigger phrases. - SKILL.md body: **under 500 lines** (< 5000 tokens). Move detailed content to `references/` files. -- File references: **one level deep** from SKILL.md only. SKILL.md links to reference files; reference files do not chain to other reference files. +- File references: **one level deep** from SKILL.md only. SKILL.md links to reference files. Reference files may link to other reference files for workflow (e.g. 01→02→04) or "see also"; avoid long chains (A→B→C→D). - Reference files over 100 lines: include a table of contents at the top. - Progressive disclosure: `name` and `description` are loaded at startup for all skills. Full SKILL.md is loaded when the skill is activated. Reference files are loaded only on demand. @@ -142,6 +142,8 @@ Skills are static files that become stale as the product evolves. Every SKILL.md Most Hookdeck doc pages are available as markdown by appending `.md` to the URL. See `event-gateway/references/referencing-docs.md` for the complete URL index. Use `allowed-tools: WebFetch` in SKILL.md frontmatter to let agents pull live docs on demand. +**CLI reference:** The full CLI reference lives at `/docs/cli` and is served there as a single HTML page. The same content is also split into separate markdown files (e.g. `/docs/cli/request.md`, `/docs/cli/event.md`, `/docs/cli/metrics.md`) so agents can fetch only the command or section they need — use these `.md` URLs when linking to a specific CLI command or when tools fetch docs as markdown for gradual discovery. + ### What belongs in SKILL.md vs references **SKILL.md:** Concise overview, key concepts, decision trees, quick copy-pasteable examples, links to reference files and live docs. Under 500 lines. @@ -150,10 +152,16 @@ Most Hookdeck doc pages are available as markdown by appending `.md` to the URL. Rule of thumb: if content is needed for every task involving this skill, it belongs in SKILL.md. If it's only needed for a specific sub-task, put it in a reference file. +### When to use CLI vs API (and Terraform for IaC) + +Direct the agent to the right resource based on the task. **CLI** = good first touch point (tasks, simple scripts: single commands or short multi-command workflows from the shell). **API** = valid for querying (events, requests, attempts, metrics), complex scripts, applications, automation; and for **dynamic resource creation** (e.g. application creating sources/connections at runtime). **When in doubt, start with the CLI to explore.** For resource management (sources, destinations, connections, transformations): **API** when resources are created **dynamically** (e.g. from an app at runtime); **Terraform** or **CLI/scripts** for **effectively static** definition management (IaC); mention the [Terraform provider](https://github.com/hookdeck/terraform-provider-hookdeck) for IaC. Skills should give this top-level guidance; surface both CLI and API querying; link to main docs for how-to details. + ### Prescriptive guidance over syntax documentation Reference files should teach the agent **how to think** about the problem. Provide decision trees, top patterns, and common gotchas. Link to live docs for comprehensive syntax reference. Follow the Neon model: minimal examples, point to live docs for the rest. +**Commands and options:** Include a **reasonable capability summary** (e.g. key commands with brief purpose) so the agent can discover what's possible without fetching first; then the agent fetches the canonical reference for the full list. Summaries may go slightly out of date—acceptable for discovery. Always **link to the canonical reference** (e.g. [CLI reference](https://hookdeck.com/docs/cli), API docs). Avoid exhaustive lists that duplicate the docs. + ### Working examples The `examples/` directory contains runnable code (Express, Next.js, FastAPI Hookdeck verification handlers). Stage `02-scaffold` references these for agent scaffolding. Keep examples focused on the minimum needed to demonstrate the pattern. @@ -185,7 +193,7 @@ When you are **adding a new skill** or **updating an existing skill** in this re - Prefer **try install first:** have the agent run `npx skills add hookdeck/webhook-skills --skill -webhooks` to verify the provider skill exists; if install fails, fall back to looking up the webhook-skills repo or informing the user. - Keep provider guidance **generic:** refer to "provider SDK verification and event construction" and "constructs provided by the provider's SDK" (e.g. Stripe `constructEvent`, Shopify HMAC as examples, not Stripe-only). - Instruct the agent to **recommend to the user** that they install the provider webhook skill (e.g. "I recommend installing the stripe-webhooks skill... Run: `npx skills add hookdeck/webhook-skills --skill stripe-webhooks`"). -4. **One level deep:** All references from SKILL.md must be to files directly in that skill's directory (e.g. `references/...`). Reference files do not chain to other reference files. +4. **One level deep:** All references from SKILL.md must be to files directly in that skill's directory (e.g. `references/...`). Reference files may link to other reference files for workflow or see-also; avoid long chains. 5. **Link to live docs** inline where a concept or feature is first mentioned; do not consolidate links in a single section. --- @@ -200,13 +208,14 @@ Before merging a new or updated skill, verify: - [ ] `name` matches parent directory name exactly - [ ] `description` is third person with "Use when..." trigger phrases - [ ] SKILL.md body is under 500 lines -- [ ] All file references are one level deep from SKILL.md +- [ ] All file references are one level deep from SKILL.md; ref→ref only one-hop (workflow/see-also), no long chains - [ ] Reference files over 100 lines have a table of contents at the top ### Hookdeck conventions - [ ] Uses correct terminology from the glossary above - [ ] When mentioning requests, events, and attempts together, uses order **request → event → attempt** (data flow) +- [ ] **When to use CLI vs API:** Direct the agent to the right resource based on the task; tasks/simple scripts → CLI, complex scripts/apps/automation → API, when in doubt start with CLI to explore; both querying paths present; main docs for details. Optional: when resource management (sources, destinations, connections, transformations) is in scope, mention the [Terraform provider](https://github.com/hookdeck/terraform-provider-hookdeck) for IaC. - [ ] Links to at least one live documentation page - [ ] No general webhook/API education that agents already know - [ ] No time-sensitive information (dates, version predictions) @@ -216,6 +225,7 @@ Before merging a new or updated skill, verify: ### Quality - [ ] Provides Hookdeck-specific value (CLI commands, filter syntax, config patterns, URL formats) +- [ ] **Capability summaries:** Reasonable command/option summaries for discovery; always link to canonical reference (CLI/API docs) for full, current list; avoid exhaustive lists that duplicate docs - [ ] Quick examples are copy-pasteable - [ ] Decision trees or conditional workflows where multiple paths exist - [ ] Cross-references related skills where appropriate diff --git a/skills/event-gateway/SKILL.md b/skills/event-gateway/SKILL.md index 8e24afc..ec1796b 100644 --- a/skills/event-gateway/SKILL.md +++ b/skills/event-gateway/SKILL.md @@ -46,9 +46,9 @@ When the user asks to verify the Hookdeck signature or build a webhook handler t - **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 +## Workflow Stages (getting started) -Follow these in order for a new Hookdeck integration: +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](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 @@ -73,7 +73,7 @@ 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`). +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`). For a full step-by-step with account and handler (create connection, scaffold, listen, iterate), follow the **Workflow Stages** above. **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. @@ -98,11 +98,18 @@ Use as needed (not sequential): ### Development & Operations +Direct yourself to the right resource based on the task. **Use the CLI first to explore** and for simple tasks; then choose the API or Terraform when things are more complex. The CLI is a good first touch for tasks and for some analysis; you can use the API for querying too. **Tasks and simple scripts** (single commands or short multi-command workflows from the shell) **→ use the CLI.** **Complex scripts, applications, and automation → use the API.** When in doubt, start with the CLI to explore. 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](https://github.com/hookdeck/terraform-provider-hookdeck). For details on performing querying, metrics, or inspection (either path), see the main documentation. + | 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 | +| **Resources** (sources, destinations, connections, transformations) | [references/01-setup.md](references/01-setup.md), [references/cli-workflows.md](references/cli-workflows.md) | First connection or adding/changing sources, destinations, connections, transformations: 01-setup for initial setup; cli-workflows for CLI create/upsert; [Sources](https://hookdeck.com/docs/sources), [Destinations](https://hookdeck.com/docs/destinations), [Connections](https://hookdeck.com/docs/connections), [Transformations](https://hookdeck.com/docs/transformations) for full reference | +| Monitoring | [references/monitoring-debugging.md](references/monitoring-debugging.md#monitoring) | Event lifecycle, where to observe (TUI, Dashboard) | +| Debugging | [references/monitoring-debugging.md](references/monitoring-debugging.md#debugging) | Troubleshooting, issues, replay | +| Querying (CLI) | [references/monitoring-debugging.md](references/monitoring-debugging.md#cli-querying) | List, inspect, retry request/event/attempt; detailed search; main docs for details | +| Metrics (CLI) | [references/monitoring-debugging.md](references/monitoring-debugging.md#cli-metrics) | Event volume, failure rates, backlog; aggregated view; main docs for details | +| CLI | [references/cli-workflows.md](references/cli-workflows.md) | Install, listen, connection/resource management, project switching | +| API | [references/api-patterns.md](references/api-patterns.md) | Querying; building apps; **dynamic** resource creation (e.g. app creating sources/connections at runtime); complex scripts; main docs for details | +| Terraform | [terraform-provider-hookdeck](https://github.com/hookdeck/terraform-provider-hookdeck) | **Static** resource management (sources, destinations, connections, transformations) as IaC; [Registry docs](https://registry.terraform.io/providers/hookdeck/hookdeck/latest/docs) | | Iterate | [references/04-iterate.md](references/04-iterate.md) | Debug failures, replay events, CLI inspect/retry workflow | ### Verification Code diff --git a/skills/event-gateway/references/04-iterate.md b/skills/event-gateway/references/04-iterate.md index bcf947a..769cf91 100644 --- a/skills/event-gateway/references/04-iterate.md +++ b/skills/event-gateway/references/04-iterate.md @@ -103,4 +103,4 @@ curl -X POST https://api.hookdeck.com/$API_VERSION/events/{event_id}/retry \ -H "Authorization: Bearer $HOOKDECK_API_KEY" ``` -See [api-patterns.md](api-patterns.md) for full API patterns and [referencing-docs.md](referencing-docs.md) for the API version. +For full API patterns, fetch the [API docs](https://hookdeck.com/docs/api.md). For doc URLs and API version, see [referencing-docs.md](referencing-docs.md). diff --git a/skills/event-gateway/references/cli-workflows.md b/skills/event-gateway/references/cli-workflows.md index e1c5965..850f194 100644 --- a/skills/event-gateway/references/cli-workflows.md +++ b/skills/event-gateway/references/cli-workflows.md @@ -9,7 +9,7 @@ - [Gateway resource management](#gateway-resource-management) - [Project Management](#project-management) -Common workflows using the Hookdeck CLI. For the full CLI reference, fetch [/docs/cli.md](https://hookdeck.com/docs/cli.md). +For **tasks and simple scripts** (querying, metrics, monitoring, debugging), the CLI is a good first touch point; use it to explore when unsure. For complex scripts, applications, or automation, use the API. When in doubt, start with the CLI to explore. This file covers: installation, listening, connection and resource management, project switching, and querying (list commands and metrics). For the full CLI reference, fetch [/docs/cli.md](https://hookdeck.com/docs/cli.md). ## Installation @@ -223,7 +223,7 @@ hookdeck gateway attempt list --event-id evt_xxx hookdeck gateway attempt get att_xxx ``` -**Metrics** (event/request/attempt/queue/pending/transformations over time): use `hookdeck gateway metrics` with subcommands `events`, `requests`, `attempts`, `queue-depth`, `pending`, `events-by-issue`, `transformations`. Required: `--start`, `--end`, `--measures`. See [monitoring-debugging.md](monitoring-debugging.md#cli-metrics) or [Metrics docs](https://hookdeck.com/docs/metrics) for examples. For the full CLI metrics reference, fetch [/docs/cli/metrics.md](https://hookdeck.com/docs/cli/metrics.md). +**Metrics** (event/request/attempt/queue/pending/transformations over time): for questions like *which connections had the most events?*, *what's our failure rate?*, or *where is backlog building?*, use `hookdeck gateway metrics` with subcommands `events`, `requests`, `attempts`, `queue-depth`, `pending`, `events-by-issue`, `transformations`. Required: `--start`, `--end`, `--measures`. See [monitoring-debugging.md](monitoring-debugging.md#cli-metrics) or [Metrics docs](https://hookdeck.com/docs/metrics) for examples. For the full CLI metrics reference, fetch [/docs/cli/metrics.md](https://hookdeck.com/docs/cli/metrics.md). ```sh hookdeck gateway metrics events --start 2026-02-01T00:00:00Z --end 2026-02-25T00:00:00Z --measures count,failed_count,error_rate @@ -245,8 +245,6 @@ For the full project reference, fetch [/docs/cli/project.md](https://hookdeck.co ## Documentation -- [CLI reference](https://hookdeck.com/docs/cli) -- [Listen command](https://hookdeck.com/docs/cli/listen) -- [Connection commands](https://hookdeck.com/docs/cli/connection) -- [Project commands](https://hookdeck.com/docs/cli/project) -- [Source](https://hookdeck.com/docs/cli/source) · [Destination](https://hookdeck.com/docs/cli/destination) · [Transformation](https://hookdeck.com/docs/cli/transformation) · [Request](https://hookdeck.com/docs/cli/request) · [Event](https://hookdeck.com/docs/cli/event) · [Attempt](https://hookdeck.com/docs/cli/attempt) · [Metrics](https://hookdeck.com/docs/cli/metrics) +- [CLI reference](https://hookdeck.com/docs/cli) (overview; per-command content is served as Markdown) +- [Listen](https://hookdeck.com/docs/cli/listen.md) · [Connection](https://hookdeck.com/docs/cli/connection.md) · [Project](https://hookdeck.com/docs/cli/project.md) +- [Source](https://hookdeck.com/docs/cli/source.md) · [Destination](https://hookdeck.com/docs/cli/destination.md) · [Transformation](https://hookdeck.com/docs/cli/transformation.md) · [Request](https://hookdeck.com/docs/cli/request.md) · [Event](https://hookdeck.com/docs/cli/event.md) · [Attempt](https://hookdeck.com/docs/cli/attempt.md) · [Metrics](https://hookdeck.com/docs/cli/metrics.md) diff --git a/skills/event-gateway/references/connection-rules.md b/skills/event-gateway/references/connection-rules.md index 372b8c5..f367d79 100644 --- a/skills/event-gateway/references/connection-rules.md +++ b/skills/event-gateway/references/connection-rules.md @@ -155,7 +155,7 @@ hookdeck gateway connection create \ --rules '[{"type":"retry","strategy":"exponential","interval":60000,"count":5}]' ``` -**Manual replay:** Use the CLI TUI, web console, or Dashboard to replay individual events. Use the API for bulk replay -- see [api-patterns.md](api-patterns.md). +**Manual replay:** Use the CLI TUI, web console, or Dashboard to replay individual events. Use the API for bulk replay — see [Bulk operations](https://hookdeck.com/docs/api/bulk) and [Inspect API](https://hookdeck.com/docs/api/inspect). For full reference: fetch [/docs/retries.md](https://hookdeck.com/docs/retries.md) diff --git a/skills/event-gateway/references/monitoring-debugging.md b/skills/event-gateway/references/monitoring-debugging.md index 7cc193c..87659e2 100644 --- a/skills/event-gateway/references/monitoring-debugging.md +++ b/skills/event-gateway/references/monitoring-debugging.md @@ -2,19 +2,26 @@ ## Contents -- [Event Lifecycle](#event-lifecycle) -- [Data Model](#data-model) -- [Event Statuses](#event-statuses) -- [Debugging Surfaces](#debugging-surfaces) -- [CLI metrics](#cli-metrics) -- [Troubleshooting Flowchart](#troubleshooting-flowchart) -- [Issues and Notifications](#issues-and-notifications) -- [Replay](#replay) +- [Monitoring](#monitoring) + - [Event Lifecycle](#event-lifecycle) + - [Data Model](#data-model) + - [Event Statuses](#event-statuses) + - [Where to look](#where-to-look) +- [Debugging](#debugging) + - [Troubleshooting Flowchart](#troubleshooting-flowchart) + - [Issues and Notifications](#issues-and-notifications) + - [Replay](#replay) +- [CLI: list and inspect](#cli-querying) +- [CLI: metrics](#cli-metrics) - [Documentation](#documentation) -How to monitor webhook deliveries, debug failures, and replay events. +How to monitor webhook deliveries, debug failures, and replay events. For monitoring and debugging, the CLI is often the right first touch for tasks and simple scripts (TUI, list/get, metrics, retry); use it to explore when unsure. The API is valid for querying and for complex scripts or automation. When in doubt, start with the CLI to explore. See SKILL.md for when-to-use guidance and main documentation for details. Querying (events, requests, attempts, metrics) can also be done via the API — see the [API inspect docs](https://hookdeck.com/docs/api/inspect). -## Event Lifecycle +## Monitoring {#monitoring} + +Event lifecycle, data model, event statuses, and where to look (CLI TUI, Web Console, Dashboard). + +### Event Lifecycle 1. Webhook provider sends a request to your Source URL (`https://hkdk.events/xxx`) 2. Hookdeck creates a [Request](https://hookdeck.com/docs/requests) (the raw inbound data) @@ -22,7 +29,7 @@ How to monitor webhook deliveries, debug failures, and replay events. 4. Hookdeck delivers the Event to the Destination, creating an [Attempt](https://hookdeck.com/docs/events) 5. If delivery fails (non-2xx), Hookdeck retries according to the Connection's retry rules -## Data Model +### Data Model | Entity | What it is | |--------|------------| @@ -32,7 +39,7 @@ How to monitor webhook deliveries, debug failures, and replay events. One Request can produce multiple Events (fan-out). Each Event has one or more Attempts. -## Event Statuses +### Event Statuses | Status | Meaning | |--------|---------| @@ -41,17 +48,17 @@ One Request can produce multiple Events (fan-out). Each Event has one or more At | `QUEUED` | Scheduled for delivery or retry | | `HOLD` | Paused by a delay rule or manual hold | -## Debugging Surfaces +### Where to look -### CLI TUI +#### CLI TUI Built into `hookdeck listen`. View events in real time, inspect request/response details, replay events -- all in the terminal. -### Web Console +#### Web Console When not using an Event Gateway project, the CLI provides a link to a web interface for event inspection and replay. -### Dashboard +#### Dashboard When using an Event Gateway project, the [Hookdeck Dashboard](https://dashboard.hookdeck.com) provides: @@ -61,9 +68,64 @@ When using an Event Gateway project, the [Hookdeck Dashboard](https://dashboard. - **Replay**: Re-deliver individual Events or bulk replay filtered sets - **Bookmarks**: Save representative Requests for repeated testing -### CLI request/event/attempt inspection +## Debugging {#debugging} + +Troubleshooting flowchart, issues and notifications, and replay. + +### Troubleshooting Flowchart + +**Events not arriving?** + +1. Is the provider sending to the correct Source URL? +2. Is `hookdeck listen` running? +3. If Source Authentication is configured, are the credentials correct? Failed auth returns `403` and no Event is created. + +**Events arriving but delivery failing?** + +1. Check the Attempt response in the CLI TUI or web UI +2. Is your handler running and listening on the correct port? +3. Is the endpoint path correct (e.g., `/webhooks` vs `/webhook`)? +4. Is the handler returning a 2xx status? Non-2xx triggers retries. + +**Signature verification failing in your handler?** + +1. Is `HOOKDECK_WEBHOOK_SECRET` set correctly? +2. Are you using the raw request body (not parsed JSON)? +3. Are you using base64 encoding (not hex)? +4. See [verification-code.md](verification-code.md) for debugging code + +### Issues and Notifications + +[Issues](https://hookdeck.com/docs/issues) are automatically created when problems are detected: + +| Issue type | Trigger | +|------------|---------| +| Delivery | Consecutive failed delivery attempts | +| Transformation | JavaScript errors in transform rules | +| Backpressure | Events queuing faster than they can be delivered | + +Issue lifecycle: `OPENED` -> `ACKNOWLEDGED` -> `RESOLVED` or `IGNORED` + +[Issue triggers](https://hookdeck.com/docs/issue-triggers) control what creates issues. [Notifications](https://hookdeck.com/docs/issue-triggers) can be sent to Email, Slack, PagerDuty, Microsoft Teams, or a webhook. + +### Replay + +**Single event replay**: Use the CLI TUI, web console, or Dashboard to replay any event. + +**Bulk retry via API**: + +```sh +curl -X POST https://api.hookdeck.com/$API_VERSION/bulk/events/retry \ + -H "Authorization: Bearer $HOOKDECK_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{"query": {"webhook_id": "web_xxx", "status": "FAILED"}}' +``` + +**[Bookmarks](https://hookdeck.com/docs/bookmarks)**: Save a Request as a bookmark in the Dashboard, then replay it whenever you need to re-test. + +## CLI: list and inspect {#cli-querying} -From the terminal you can list, inspect, and retry without opening the Dashboard. Order reflects data flow: request → events → attempts. +When to use: detailed search, inspecting or retrying individual request, event, or attempt. From the terminal you can list, inspect, and retry without opening the Dashboard. Order reflects data flow: request → events → attempts. ```sh hookdeck gateway request list @@ -76,11 +138,11 @@ hookdeck gateway attempt list --event-id evt_xxx hookdeck gateway attempt get att_xxx ``` -See [Request commands](https://hookdeck.com/docs/cli/request.md), [Event commands](https://hookdeck.com/docs/cli/event.md), and [Attempt commands](https://hookdeck.com/docs/cli/attempt.md) for full options. +See [Request commands](https://hookdeck.com/docs/cli/request.md), [Event commands](https://hookdeck.com/docs/cli/event.md), and [Attempt commands](https://hookdeck.com/docs/cli/attempt.md) for full options. For aggregated metrics (volume, failure rate, backlog), see [CLI: metrics](#cli-metrics) in this file. -### CLI metrics {#cli-metrics} +## CLI: metrics {#cli-metrics} -Metrics over time are available in the [Dashboard](https://dashboard.hookdeck.com) ([Metrics page](https://dashboard.hookdeck.com/metrics) and Source/Connection/Destination pages) and via `hookdeck gateway metrics` and its subcommands. All CLI commands require a date range (`--start`, `--end`, ISO 8601) and at least one `--measures` value; optional filters include `--granularity`, `--dimensions`, `--source-id`, `--destination-id`, `--connection-id`, and `--status`. See [Metrics](https://hookdeck.com/docs/metrics) and the [CLI metrics reference](https://hookdeck.com/docs/cli/metrics) for full reference. +When to use: event volume, failure rates, which connections had the most events, backlog. Questions like *which connections had the most events?*, *what's our failure rate?*, or *where is backlog building?* are answered from the terminal with the metrics subcommands below. For listing or inspecting individual requests, events, or attempts, see [CLI: list and inspect](#cli-querying). Metrics over time are also available in the [Dashboard](https://dashboard.hookdeck.com) ([Metrics page](https://dashboard.hookdeck.com/metrics) and Source/Connection/Destination pages). The CLI uses `hookdeck gateway metrics` and its subcommands. All CLI commands require a date range (`--start`, `--end`, ISO 8601) and at least one `--measures` value; optional filters include `--granularity`, `--dimensions`, `--source-id`, `--destination-id`, `--connection-id`, and `--status`. See [Metrics](https://hookdeck.com/docs/metrics) and the [CLI metrics reference](https://hookdeck.com/docs/cli/metrics.md) for full reference. | Subcommand | Purpose | |------------|---------| @@ -136,61 +198,6 @@ Transformation errors: hookdeck gateway metrics transformations --start 2026-02-01T00:00:00Z --end 2026-02-25T00:00:00Z --measures count,failed_count,error_rate ``` -### REST API - -Use the API programmatically -- see [api-patterns.md](api-patterns.md). - -## Troubleshooting Flowchart - -**Events not arriving?** - -1. Is the provider sending to the correct Source URL? -2. Is `hookdeck listen` running? -3. If Source Authentication is configured, are the credentials correct? Failed auth returns `403` and no Event is created. - -**Events arriving but delivery failing?** - -1. Check the Attempt response in the CLI TUI or web UI -2. Is your handler running and listening on the correct port? -3. Is the endpoint path correct (e.g., `/webhooks` vs `/webhook`)? -4. Is the handler returning a 2xx status? Non-2xx triggers retries. - -**Signature verification failing in your handler?** - -1. Is `HOOKDECK_WEBHOOK_SECRET` set correctly? -2. Are you using the raw request body (not parsed JSON)? -3. Are you using base64 encoding (not hex)? -4. See [verification-code.md](verification-code.md) for debugging code - -## Issues and Notifications - -[Issues](https://hookdeck.com/docs/issues) are automatically created when problems are detected: - -| Issue type | Trigger | -|------------|---------| -| Delivery | Consecutive failed delivery attempts | -| Transformation | JavaScript errors in transform rules | -| Backpressure | Events queuing faster than they can be delivered | - -Issue lifecycle: `OPENED` -> `ACKNOWLEDGED` -> `RESOLVED` or `IGNORED` - -[Issue triggers](https://hookdeck.com/docs/issue-triggers) control what creates issues. [Notifications](https://hookdeck.com/docs/issue-triggers) can be sent to Email, Slack, PagerDuty, Microsoft Teams, or a webhook. - -## Replay - -**Single event replay**: Use the CLI TUI, web console, or Dashboard to replay any event. - -**Bulk retry via API**: - -```sh -curl -X POST https://api.hookdeck.com/$API_VERSION/bulk/events/retry \ - -H "Authorization: Bearer $HOOKDECK_API_KEY" \ - -H "Content-Type: application/json" \ - -d '{"query": {"webhook_id": "web_xxx", "status": "FAILED"}}' -``` - -**[Bookmarks](https://hookdeck.com/docs/bookmarks)**: Save a Request as a bookmark in the Dashboard, then replay it whenever you need to re-test. - ## Documentation - [Events & Attempts](https://hookdeck.com/docs/events) @@ -199,4 +206,4 @@ curl -X POST https://api.hookdeck.com/$API_VERSION/bulk/events/retry \ - [Issue triggers](https://hookdeck.com/docs/issue-triggers) - [Metrics](https://hookdeck.com/docs/metrics) - [Bookmarks](https://hookdeck.com/docs/bookmarks) -- CLI: [request](https://hookdeck.com/docs/cli/request) · [event](https://hookdeck.com/docs/cli/event) · [attempt](https://hookdeck.com/docs/cli/attempt) · [source](https://hookdeck.com/docs/cli/source) · [destination](https://hookdeck.com/docs/cli/destination) · [transformation](https://hookdeck.com/docs/cli/transformation) +- CLI: [request](https://hookdeck.com/docs/cli/request.md) · [event](https://hookdeck.com/docs/cli/event.md) · [attempt](https://hookdeck.com/docs/cli/attempt.md) · [source](https://hookdeck.com/docs/cli/source.md) · [destination](https://hookdeck.com/docs/cli/destination.md) · [transformation](https://hookdeck.com/docs/cli/transformation.md) · [metrics](https://hookdeck.com/docs/cli/metrics.md) From 4b191cac4807ebddd612421f96d3eec00d554b89 Mon Sep 17 00:00:00 2001 From: Phil Leggetter Date: Fri, 27 Feb 2026 10:32:37 +0000 Subject: [PATCH 2/4] Context verification: always show whoami; confirm unless user clearly identified org/project and exact match - SKILL.md: numbered steps for context verification; step 2 asks for confirmation unless user clearly identified org/project and whoami matches. Workflow callout and Dev & Ops table updated. - cli-workflows.md: verify before queries/metrics; always show whoami output; ask to confirm unless clear user-specified match. - monitoring-debugging.md: checklist adds 'show output' and 'confirm unless clear match'; common mistake updated. Made-with: Cursor --- skills/event-gateway/SKILL.md | 13 ++++++ .../event-gateway/references/cli-workflows.md | 41 +++++++++++++------ .../references/monitoring-debugging.md | 12 ++++++ 3 files changed, 54 insertions(+), 12 deletions(-) diff --git a/skills/event-gateway/SKILL.md b/skills/event-gateway/SKILL.md index ec1796b..c815a70 100644 --- a/skills/event-gateway/SKILL.md +++ b/skills/event-gateway/SKILL.md @@ -55,6 +55,8 @@ This is the recommended path for a new integration: create sources, destinations 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 +> **Before any queries or metrics:** 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](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) @@ -75,6 +77,16 @@ 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`). For a full step-by-step with account and handler (create connection, scaffold, listen, iterate), 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](https://hookdeck.com/docs/projects). 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 `, 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](references/cli-workflows.md#project-management) for details. + **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 @@ -102,6 +114,7 @@ Direct yourself to the right resource based on the task. **Use the CLI first to | 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](references/cli-workflows.md#project-management) | | **Resources** (sources, destinations, connections, transformations) | [references/01-setup.md](references/01-setup.md), [references/cli-workflows.md](references/cli-workflows.md) | First connection or adding/changing sources, destinations, connections, transformations: 01-setup for initial setup; cli-workflows for CLI create/upsert; [Sources](https://hookdeck.com/docs/sources), [Destinations](https://hookdeck.com/docs/destinations), [Connections](https://hookdeck.com/docs/connections), [Transformations](https://hookdeck.com/docs/transformations) for full reference | | Monitoring | [references/monitoring-debugging.md](references/monitoring-debugging.md#monitoring) | Event lifecycle, where to observe (TUI, Dashboard) | | Debugging | [references/monitoring-debugging.md](references/monitoring-debugging.md#debugging) | Troubleshooting, issues, replay | diff --git a/skills/event-gateway/references/cli-workflows.md b/skills/event-gateway/references/cli-workflows.md index 850f194..90625f8 100644 --- a/skills/event-gateway/references/cli-workflows.md +++ b/skills/event-gateway/references/cli-workflows.md @@ -4,10 +4,10 @@ - [Installation](#installation) - [Authentication](#authentication) +- [Project Management](#project-management) - [Listening for Events](#listening-for-events) - [Connection Management](#connection-management) - [Gateway resource management](#gateway-resource-management) -- [Project Management](#project-management) For **tasks and simple scripts** (querying, metrics, monitoring, debugging), the CLI is a good first touch point; use it to explore when unsure. For complex scripts, applications, or automation, use the API. When in doubt, start with the CLI to explore. This file covers: installation, listening, connection and resource management, project switching, and querying (list commands and metrics). For the full CLI reference, fetch [/docs/cli.md](https://hookdeck.com/docs/cli.md). @@ -44,6 +44,34 @@ hookdeck logout # Clear credentials hookdeck whoami # Show current user and project ``` +## Project Management {#project-management} + +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. **Verify before any queries or metrics:** run whoami and **show the user the output**. 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 before running queries or metrics. See [Projects](https://hookdeck.com/docs/projects) for details. + +**Check current context:** + +```sh +hookdeck whoami +``` + +Output shows the current user, organization, and project. **Always show this output to the user.** Unless they have clearly specified org/project and it matches, ask them to confirm it is the correct organization and project before running any queries or metrics. If the user says it's wrong (or you see a different organization or project than they asked for), switch before querying. + +**List available organizations and projects:** + +```sh +hookdeck project list +``` + +**Switch to a specific organization and project:** + +```sh +hookdeck project use +``` + +Example: `hookdeck project use prod "Default Project"`. Then run `hookdeck whoami` again to confirm. + +For the full project reference, fetch [/docs/cli/project.md](https://hookdeck.com/docs/cli/project.md). + ## Listening for Events `hookdeck listen` is the primary command. It creates a tunnel from a public Hookdeck URL to your local server. @@ -232,17 +260,6 @@ hookdeck gateway metrics queue-depth --start 2026-02-01T00:00:00Z --end 2026-02- For full flag and option details, fetch [/docs/cli.md](https://hookdeck.com/docs/cli.md) or the per-command pages: [/docs/cli/source.md](https://hookdeck.com/docs/cli/source.md), [/docs/cli/destination.md](https://hookdeck.com/docs/cli/destination.md), [/docs/cli/transformation.md](https://hookdeck.com/docs/cli/transformation.md), [/docs/cli/request.md](https://hookdeck.com/docs/cli/request.md), [/docs/cli/event.md](https://hookdeck.com/docs/cli/event.md), [/docs/cli/attempt.md](https://hookdeck.com/docs/cli/attempt.md), [/docs/cli/metrics.md](https://hookdeck.com/docs/cli/metrics.md). -## Project Management - -Switch between projects: - -```sh -hookdeck project list -hookdeck project use my-org my-project -``` - -For the full project reference, fetch [/docs/cli/project.md](https://hookdeck.com/docs/cli/project.md). - ## Documentation - [CLI reference](https://hookdeck.com/docs/cli) (overview; per-command content is served as Markdown) diff --git a/skills/event-gateway/references/monitoring-debugging.md b/skills/event-gateway/references/monitoring-debugging.md index 87659e2..99fce57 100644 --- a/skills/event-gateway/references/monitoring-debugging.md +++ b/skills/event-gateway/references/monitoring-debugging.md @@ -2,6 +2,7 @@ ## Contents +- [Before querying or running metrics](#before-querying-or-running-metrics) - [Monitoring](#monitoring) - [Event Lifecycle](#event-lifecycle) - [Data Model](#data-model) @@ -17,6 +18,17 @@ How to monitor webhook deliveries, debug failures, and replay events. For monitoring and debugging, the CLI is often the right first touch for tasks and simple scripts (TUI, list/get, metrics, retry); use it to explore when unsure. The API is valid for querying and for complex scripts or automation. When in doubt, start with the CLI to explore. See SKILL.md for when-to-use guidance and main documentation for details. Querying (events, requests, attempts, metrics) can also be done via the API — see the [API inspect docs](https://hookdeck.com/docs/api/inspect). +## Before querying or running metrics {#before-querying-or-running-metrics} + +All list, inspect, and metrics commands are scoped to the **current [organization and project](https://hookdeck.com/docs/projects)** (organization = top-level account; project = where your sources, connections, and destinations live). + +- [ ] 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 running queries or metrics +- [ ] If not correct, use `hookdeck project list` to see options, then `hookdeck project use ` +- [ ] Run `hookdeck whoami` again, show the output, and (unless clear match) ask the user to confirm again before running queries or metrics + +**Common mistake:** Running a metrics query without verifying org/project — data can come from the wrong organization (e.g. "Automated Testing" instead of "prod"). **Correct approach:** Run `hookdeck whoami` and show the output. If the user hasn't clearly specified org/project or it doesn't match, ask them to confirm; if not correct, switch and confirm again. Only then run the query. + ## Monitoring {#monitoring} Event lifecycle, data model, event statuses, and where to look (CLI TUI, Web Console, Dashboard). From 59cb35a961998669454e0bb81794a43ff21dcdca Mon Sep 17 00:00:00 2001 From: Phil Leggetter Date: Fri, 27 Feb 2026 10:57:47 +0000 Subject: [PATCH 3/4] chore: Update 04-iterate.md to enhance documentation clarity by linking to API Patterns for common uses and providing a more comprehensive overview of API documentation references. --- skills/event-gateway/references/04-iterate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/event-gateway/references/04-iterate.md b/skills/event-gateway/references/04-iterate.md index 769cf91..88264cf 100644 --- a/skills/event-gateway/references/04-iterate.md +++ b/skills/event-gateway/references/04-iterate.md @@ -103,4 +103,4 @@ curl -X POST https://api.hookdeck.com/$API_VERSION/events/{event_id}/retry \ -H "Authorization: Bearer $HOOKDECK_API_KEY" ``` -For full API patterns, fetch the [API docs](https://hookdeck.com/docs/api.md). For doc URLs and API version, see [referencing-docs.md](referencing-docs.md). +See [API Patterns](api-patterns.md) for an overview of common uses of the Hookdeck Event Gateway API. See the [API docs](https://hookdeck.com/docs/api.md) for full API details. To see how to reference documentation and a general overview of key available docs, see [referencing-docs.md](referencing-docs.md). From c433f85379a878d4211abd2b8e514609216bea0b Mon Sep 17 00:00:00 2001 From: Phil Leggetter Date: Fri, 27 Feb 2026 11:19:44 +0000 Subject: [PATCH 4/4] chore: update links directly to .md when the HTML resource doesn't exist --- AGENTS.md | 2 ++ skills/event-gateway/references/api-patterns.md | 10 +++++----- skills/event-gateway/references/connection-rules.md | 2 +- .../event-gateway/references/monitoring-debugging.md | 2 +- 4 files changed, 9 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b72f9a4..cd191d9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -144,6 +144,8 @@ Most Hookdeck doc pages are available as markdown by appending `.md` to the URL. **CLI reference:** The full CLI reference lives at `/docs/cli` and is served there as a single HTML page. The same content is also split into separate markdown files (e.g. `/docs/cli/request.md`, `/docs/cli/event.md`, `/docs/cli/metrics.md`) so agents can fetch only the command or section they need — use these `.md` URLs when linking to a specific CLI command or when tools fetch docs as markdown for gradual discovery. +**API reference:** The full API reference lives at `/docs/api` as a single HTML page. Sub-resources (e.g. inspect, bulk, connections) are **not** separate HTML pages; they exist as markdown files (e.g. `/docs/api/inspect.md`, `/docs/api/bulk.md`, `/docs/api/connections.md`). Link directly to `.md` URLs for API sub-resources so agents and tools get fetchable content; links to `/docs/api/foo` without `.md` will 404. + ### What belongs in SKILL.md vs references **SKILL.md:** Concise overview, key concepts, decision trees, quick copy-pasteable examples, links to reference files and live docs. Under 500 lines. diff --git a/skills/event-gateway/references/api-patterns.md b/skills/event-gateway/references/api-patterns.md index dcf32ab..9628be7 100644 --- a/skills/event-gateway/references/api-patterns.md +++ b/skills/event-gateway/references/api-patterns.md @@ -137,8 +137,8 @@ curl "https://api.hookdeck.com/$API_VERSION/events?limit=25&next=cursor_xxx" \ ## Documentation -- [API overview](https://hookdeck.com/docs/api) -- [Connections API](https://hookdeck.com/docs/api/connections) -- [Inspect API (requests, events, attempts)](https://hookdeck.com/docs/api/inspect) -- [Bulk operations](https://hookdeck.com/docs/api/bulk) -- [Publish API](https://hookdeck.com/docs/api/publish) +- [API overview](https://hookdeck.com/docs/api.md) +- [Connections API](https://hookdeck.com/docs/api/connections.md) +- [Inspect API (requests, events, attempts)](https://hookdeck.com/docs/api/inspect.md) +- [Bulk operations](https://hookdeck.com/docs/api/bulk.md) +- [Publish API](https://hookdeck.com/docs/api/publish.md) diff --git a/skills/event-gateway/references/connection-rules.md b/skills/event-gateway/references/connection-rules.md index f367d79..f58e095 100644 --- a/skills/event-gateway/references/connection-rules.md +++ b/skills/event-gateway/references/connection-rules.md @@ -155,7 +155,7 @@ hookdeck gateway connection create \ --rules '[{"type":"retry","strategy":"exponential","interval":60000,"count":5}]' ``` -**Manual replay:** Use the CLI TUI, web console, or Dashboard to replay individual events. Use the API for bulk replay — see [Bulk operations](https://hookdeck.com/docs/api/bulk) and [Inspect API](https://hookdeck.com/docs/api/inspect). +**Manual replay:** Use the CLI TUI, web console, or Dashboard to replay individual events. Use the API for bulk replay — see [Bulk operations](https://hookdeck.com/docs/api/bulk.md) and [Inspect API](https://hookdeck.com/docs/api/inspect.md). For full reference: fetch [/docs/retries.md](https://hookdeck.com/docs/retries.md) diff --git a/skills/event-gateway/references/monitoring-debugging.md b/skills/event-gateway/references/monitoring-debugging.md index 99fce57..5655fe3 100644 --- a/skills/event-gateway/references/monitoring-debugging.md +++ b/skills/event-gateway/references/monitoring-debugging.md @@ -16,7 +16,7 @@ - [CLI: metrics](#cli-metrics) - [Documentation](#documentation) -How to monitor webhook deliveries, debug failures, and replay events. For monitoring and debugging, the CLI is often the right first touch for tasks and simple scripts (TUI, list/get, metrics, retry); use it to explore when unsure. The API is valid for querying and for complex scripts or automation. When in doubt, start with the CLI to explore. See SKILL.md for when-to-use guidance and main documentation for details. Querying (events, requests, attempts, metrics) can also be done via the API — see the [API inspect docs](https://hookdeck.com/docs/api/inspect). +How to monitor webhook deliveries, debug failures, and replay events. For monitoring and debugging, the CLI is often the right first touch for tasks and simple scripts (TUI, list/get, metrics, retry); use it to explore when unsure. The API is valid for querying and for complex scripts or automation. When in doubt, start with the CLI to explore. See SKILL.md for when-to-use guidance and main documentation for details. Querying (events, requests, attempts, metrics) can also be done via the API — see the [API inspect docs](https://hookdeck.com/docs/api/inspect.md). ## Before querying or running metrics {#before-querying-or-running-metrics}