AGENT SKILL

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

  1. New webhook: define event_id + signature verification BEFORE the handler.
  2. Provider test event: validate signature and end-to-end processing.
  3. Test a real duplicate: send the same event 2x and confirm single effect.
  4. 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

Leostruka
Leostruka/devin-bundle

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.

★ 0
Leostruka
Leostruka/devin-bundle

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.

★ 0
Leostruka
Leostruka/devin-bundle

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.

★ 0
Leostruka
Leostruka/devin-bundle

demo

Use when demonstrating a skill in a fixture project.

★ 0
Leostruka
Leostruka/devin-bundle

duplicate-skill

Use when testing duplicate skill name detection.

★ 0
Leostruka
Leostruka/devin-bundle

duplicate-skill

Use when testing duplicate skill name detection.

★ 0