How do I install the Webhooks Design skill?

Run npx skillmds@latest add amey-thakur/webhooks-design in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Webhooks Design safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Webhooks Design?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Webhooks Design free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Webhooks Design?

Amey-Thakur (@amey-thakur) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Webhooks Design by amey-thakur — Agent Skill

Name: Webhooks Design
Author: Amey-Thakur

File contents

Webhooks design

A webhook program is a promise about delivery semantics. State the promise precisely (at-least-once, possibly out of order, within N hours) and build both sides to it.

Method

Send facts, fetch details. Payload carries event type, IDs, timestamps, and a version; consumers fetch the full object if needed. Thin payloads survive schema evolution and avoid shipping stale or sensitive data to endpoints you do not control.
Sign with a shared-secret HMAC over timestamp + body. signature: t=1712..., v1=hex(hmac_sha256(secret, t + "." + body)). The timestamp bounds replay (reject > 5 minutes old); constant-time compare; support two active secrets for rotation.
Retry on schedule, disable on despair. Anything but a 2xx within a short timeout (5-10s) is a failure; retry with exponential backoff over 24-72 hours. After exhaustion, mark the endpoint failing, notify the owner, and auto-disable persistent offenders; expose recent deliveries and a manual redeliver in the dashboard.
Guarantee at-least-once, number the events. Do not promise ordering; parallel delivery and retries reorder everything. Give each event a unique ID (consumer dedup key) and a per-resource sequence or updated_at so consumers can discard stale updates.
Consume via ack-fast-process-later. Receiver verifies signature, persists the raw event, returns 200, then processes from its own queue. Processing inline behind the response is how consumers turn your retries into their duplicated side effects.
Ship the consumer-side kit. Verification snippets per language, a CLI or dashboard test-fire, event catalog with sample payloads, and a whsec_-style prefixed secret. Every hour you spend here removes a thousand support tickets.

Boundaries

Webhooks complement polling and event streams, not replace them: a /events list endpoint is the reconciliation path after consumer downtime.
Do not send webhooks to unverified URLs without SSRF controls: resolve and block private ranges, disallow redirects (see ssrf-defense).
Mutual TLS and static-IP allowlists are enterprise asks with real ops cost; price them consciously rather than promising ad hoc.

---name: webhooks-designdescription: Deliver webhooks with signatures, retries, and ordering rules consumers can actually build against. Use when adding webhooks to a product or hardening delivery and verification on either side.---# Webhooks designA webhook program is a promise about delivery semantics. State thepromise precisely (at-least-once, possibly out of order, within N hours)and build both sides to it.## Method1. **Send facts, fetch details.** Payload carries event type, IDs, timestamps, and a version; consumers fetch the full object if needed. Thin payloads survive schema evolution and avoid shipping stale or sensitive data to endpoints you do not control.2. **Sign with a shared-secret HMAC over timestamp + body.** `signature: t=1712..., v1=hex(hmac_sha256(secret, t + "." + body))`. The timestamp bounds replay (reject > 5 minutes old); constant-time compare; support two active secrets for rotation.3. **Retry on schedule, disable on despair.** Anything but a 2xx within a short timeout (5-10s) is a failure; retry with exponential backoff over 24-72 hours. After exhaustion, mark the endpoint failing, notify the owner, and auto-disable persistent offenders; expose recent deliveries and a manual redeliver in the dashboard.4. **Guarantee at-least-once, number the events.** Do not promise ordering; parallel delivery and retries reorder everything. Give each event a unique ID (consumer dedup key) and a per-resource sequence or `updated_at` so consumers can discard stale updates.5. **Consume via ack-fast-process-later.** Receiver verifies signature, persists the raw event, returns 200, then processes from its own queue. Processing inline behind the response is how consumers turn your retries into their duplicated side effects.6. **Ship the consumer-side kit.** Verification snippets per language, a CLI or dashboard test-fire, event catalog with sample payloads, and a `whsec_`-style prefixed secret. Every hour you spend here removes a thousand support tickets.## Boundaries- Webhooks complement polling and event streams, not replace them: a `/events` list endpoint is the reconciliation path after consumer downtime.- Do not send webhooks to unverified URLs without SSRF controls: resolve and block private ranges, disallow redirects (see ssrf-defense).- Mutual TLS and static-IP allowlists are enterprise asks with real ops cost; price them consciously rather than promising ad hoc.

Frequently asked questions

Webhooks Design