agentsclimarketplace
Sign in

Webhooks design

Skill Amey-Thakur/AI-SKILLS/skills/backend/webhooks-design

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.From its SKILL.md

Install
npx -y skills add Amey-Thakur/AI-SKILLS --skill webhooks-design

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

  • 24 days oldThe repository was created 24 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
  • 4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

2.4 KB, 521 tokens by cl100k_base, as published. Nobody here has run it

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

  1. 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.

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.

Keep looking

Skills are one crate of 326,750. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.