Helps you place Hookdeck Event Gateway in front of commerce webhooks before a peak, then replay missed events in capture order after an outage, with confirmation before production changes.
Prepare and recover with bfcm-webhook-playbook
Helps you put Hookdeck Event Gateway ahead of commerce webhooks before a peak, then replay missed events in capture order after an outage, once confirmed.
Source facts
- Repository
- hookdeck/webhook-skills
- Last source activity
- November 13, 2026 at 17:53
- Detected SKILL.md language
- English
- Stars
- 101
- Forks
- 16
Uses
Use this Skill when you are preparing Shopify, Stripe, BigCommerce, WooCommerce, or PayPal webhooks for Black Friday / Cyber Monday or another traffic peak, when webhook delivery is failing or an endpoint is down, when you missed webhooks during an outage and need them back, or when you need to replay missed webhooks in order without overwhelming the API. It covers two halves: Prepare — recommended, put Hookdeck Event Gateway inline in front of the endpoint before the peak so it can queue and retry if your infrastructure fails; if you cannot change where the provider sends, a standby source beside the endpoint records a copy — and Recover — stop further loss, fix the endpoint, then replay what was missed, oldest first, at a rate the system can take. This is a runbook Skill for Event Gateway via CLI, REST API, and Terraform; the Skill says there are no dashboard instructions. It is not a fully automatic setup: the agent must triage, confirm the project, dry-run bulk operations, and get explicit confirmation before changing production. The qualified post's “Our agent skill sets it up” and “every webhook gets a 200 and is queued” are post wording, recorded separately and not flattened into a broader or fully automatic capability. This draft did not run any Hookdeck, Shopify, Stripe, or webhook setup.
Prerequisites
You need a Hookdeck project and the Hookdeck CLI. The Skill requires the agent to run hookdeck whoami first; if the CLI is missing, it documents brew install hookdeck or npm i -g hookdeck-cli (those install commands are not repeated in the card summary). Authentication: if a person is at the keyboard, hookdeck login opens a browser; if they have no account yet, they can sign up at https://dashboard.hookdeck.com/signup. For CI or no browser, hookdeck ci --api-key "$HOOKDECK_API_KEY". REST API calls for bulk retries and replays, destination rate changes, and alert triggers need the project's API key (HOOKDECK_API_KEY); hookdeck login does not set it, so the agent should ask for the key from project settings and must not print it back. These tools were not installed or executed in this draft. The repository-root README is an unattached monorepo or suite README, is not this Skill's README, is not in sourceUrls, and is not LICENSE-file terms. Other provider Skills in hookdeck/webhook-skills are not this target; qualification does not transfer, and the unofficial label named-subskill-in-multi-skill-repo is not applied (current official SKILL and template text do not define that string).
How to use
The same-author install reply (https://x.com/Hookdeck/status/2121309667108536676), which is evidence for this card only and is not a second posts entry, gives this starting request after the install command (the command itself stays out of the card summary): “How do we prepare our webhooks for Black Friday?” The pinned SKILL also lists other author-given questions, including “Our webhooks are failing / our endpoint is down — what do we do?” That second wording is in the SKILL, and also in a later same-path deferred thread; it is not in the install reply's actual text.
Before running anything, the Skill tells the agent to triage two questions: (1) are you preparing, or is something failing right now? (2) how does Event Gateway sit in the path today — standby (the provider sends to your endpoint and to a connection-less Event Gateway source), inline (the provider sends only to Event Gateway, which delivers to your endpoint), or none?
Then follow the Skill's agent rules, which it marks as not optional, because recovery commands change production delivery: confirm the project with hookdeck whoami and get the user to confirm the organization and project before any state-changing command; dry-run every bulk operation's /plan endpoint, show estimated_count, and get explicit confirmation before creating it; record IDs and timestamps; never run a bulk replay twice over the same window; filter replays only on rejection_cause=NO_CONNECTION and created_at[gte] / [lte]; choose ordered versus bulk replay with the user; prefer lowering the delivery rate over pausing; set up the CLI before anything else, as in prerequisites.
Prepare goes to references/prepare.md (recommended: inline) and optional references/terraform.md. Recover goes to references/incident-inline.md, references/incident-standby.md, or references/incident-move-inline.md, depending on the setup. Those reference files are cited by the SKILL. This draft limited-read only references/provider-notes.md at the same HEAD, for comparison with post claims, and did not execute any runbook.
Limitations
The qualified post says that if the endpoint is down, “Shopify stops retrying after 4 hours” and “WooCommerce and BigCommerce disable the webhook,” and that “With Hookdeck Event Gateway in front, every webhook gets a 200 and is queued.” The pinned SKILL.md is more precise and does not repeat those provider numbers in its own body. It states that a source with no connection still records requests; for a genuine webhook, the ingestion edge returns 200 so the provider treats delivery as successful, and the request is stored as rejected with cause NO_CONNECTION; forged requests get 401 and VERIFICATION_FAILED, and recovery does not replay them. “Every webhook gets a 200” is therefore not an accurate flattening of the Skill. A limited read of references/provider-notes.md at the same HEAD (the notes say the figures were taken from provider docs checked November 2026 and should be confirmed against the linked pages) gives more precise, caveated figures: Shopify up to 8 retries over 4 hours, and Admin-API subscriptions may be deleted after repeated failures (subscriptions declared in the app configuration are described as not deleted); BigCommerce is deactivated after 11 retries over about 48 hours; WooCommerce is disabled after more than five consecutive failures. Those reference notes are source-document claims, not this site's verification, and were not upgraded to a formal source_difference hold.
Order is never guaranteed by Event Gateway or by the providers; ordered replay keeps exact capture order at about 4–5 requests a second; bulk replay is faster but shuffles order within each batch of 100. Handlers must still tolerate out-of-order and duplicate events. Payload retention is finite; replaying a request outside the plan's retention window fails with 409 DATA_ARCHIVED. Never run a bulk replay twice over the same window. Recovery commands change production delivery.
The post's “Our agent skill sets it up” is promotional wording; the Skill requires triage, project confirmation, dry-runs, and explicit human confirmation. “Black Friday is in two weeks” and “It's Friday the 13th” are post timing, not Skill capabilities. The attached video was not watched (media_inspected=false). Examples stay empty. Other Skills in hookdeck/webhook-skills were not drafted. Documented CLI, API, and Terraform were not executed.
The Skill tells the agent to ask for the project's API key and not to print it back. Webhook payloads are recorded and replayed through Hookdeck Event Gateway as the runbooks describe. The Skill does not state further privacy, telemetry, or retention-policy terms beyond finite payload retention (409 DATA_ARCHIVED). No further privacy boundary is invented. Tools were not executed.
The SKILL frontmatter declares license: MIT. A MIT LICENSE file, Copyright (c) 2026 Hookdeck, exists at the repository root of the pinned HEAD. The skill directory itself (skills/bfcm-webhook-playbook/) has no LICENSE or README. Those MIT terms were read from the repository-root LICENSE file, not from README-only claims, and not from the unattached suite README (which is not in sourceUrls). The main post does not state a license.
Install options
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Review the source files
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Showing SKILL.md
| name | bfcm-webhook-playbook |
|---|---|
| description | Black Friday / Cyber Monday (BFCM) webhook playbook: prepare webhook handling for peak commerce traffic, and recover when webhooks are failing mid-incident. Use when preparing Shopify, Stripe, BigCommerce, WooCommerce or PayPal webhooks for BFCM or another traffic peak, when webhook delivery is failing or an endpoint is down ("our webhooks are failing, what do we do?"), or when replaying missed webhooks in order after an outage. Uses the Hookdeck Event Gateway via CLI, REST API and Terraform. |