webhooks
Use when building or debugging endpoints that receive third-party callbacks (payments, GitHub, ERP). Webhook receiver discipline - signature verification, idempotency by event id, fast acknowledge with background processing, replay protection.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- webhooks
- triggers
- [ "user", "model" ]
- description
- Use when building or debugging endpoints that receive third-party callbacks (payments, GitHub, ERP). Webhook receiver discipline - signature verification, idempotency by event id, fast acknowledge with background processing, replay protection.
- allowed-tools
- [ "read", "grep", "find_file_by_name", "write", "edit", "exec" ]
03 SKILL.md 正文
Webhooks
A webhook endpoint is a public endpoint receiving POSTs from third parties: without verified signatures anyone injects events; without idempotency retries duplicate effects.
When to use
- Creating an endpoint that receives webhooks (payment, GitHub, ERP).
- Debugging duplicated or lost events.
- Reviewing an existing callback endpoint.
Hard rules
Event authentication
- ALWAYS verify the provider signature (payload HMAC with the secret, or the provider's own mechanism). Never trust the payload.
- Constant-time signature comparison (
hash_equals): normal comparison leaks timing. - Secret outside the code (secrets/env) with a rotation procedure.
Idempotency and retry
- Same event_id processed twice = effect once: store processed event_ids (table with unique constraint) and ignore duplicates.
- Respond 2xx fast (ack) and process later in a queue. Never process synchronously with the provider timeout on your neck.
- Events arrive out of order: process by state, do not assume arrival order.
Validation and surface
- Validate payload schema before using: a missing field is a malformed event, not a crash.
- Event-type whitelist; unknown type = ignore and log, never explode.
- Replay: acceptance window based on the provider timestamp.
Operations
- Structured log keyed by event_id (debug correlation).
- Queue with its own retry and dead-letter (DLQ).
- Monitor received vs processed; alert if the queue backs up.
Flow
- New webhook: define event_id + signature verification BEFORE the handler.
- Provider test event: validate signature and end-to-end processing.
- Test a real duplicate: send the same event 2x and confirm single effect.
- Test replay/lag: an old event must not corrupt state.
Anti-patterns
- Synchronous processing in the request (provider timeout = lost event and infinite retry).
- Accepting a payload without signature "because the provider is trustworthy".
- No event_id: duplicate becomes double effect (2x charge).
- Empty catch on malformed events: invisibly lost data.
- Webhook secret in code/commits.
Cascade
security: webhook secret handling and rotation, public endpoint surface.debugging: duplicated/lost event investigation.
04 同仓库更多 Skills
montador-de-ideias
Use when assembling, expanding, or elevating a raw project idea or initial prompt into an ultra-detailed, first-principles dossier and compiled master prompt with journalistic OSINT market research, Tech Lead and Staff Architect justifications, atomic and modular hardening/optimization, and high-impact contact surfaces.
git-github-adaptive-engineering
Use when any task touches git history, GitHub issues/PRs/releases/CI, repo governance, or branch and merge decisions. Runs the Fase Zero situational-awareness battery, picks one of five delivery flows via the adaptive decision engine, and enforces commit/PR information-density standards. Orchestrates the gh, git-workflows, github-actions, pr, and debug/finish skills.
adaptive-agenda-calendar-routine-engine
Use when planning or executing work across hours, days, weeks, or sprints. Turns the calendar into a strict time-blocked agenda (HH:MM-HH:MM blocks carrying a routine profile, expected inputs, and a handoff output artifact), runs the 5-stage cognitive flow (Radar and Hunt -> Triage plus Steve Jobs conception -> workbench manifest -> >=32-cycle loop -> Close plus Open-Minded Scrum), and unfolds macro calendar milestones into micro agenda blocks through extensions/gcal/wrapper.py.
demo
Use when demonstrating a skill in a fixture project.
duplicate-skill
Use when testing duplicate skill name detection.
duplicate-skill
Use when testing duplicate skill name detection.