webhook-handler-patterns

Best practices for webhook handlers. Use when implementing the handler sequence (verify first, parse second, handle idempotently), idempotency, error handling, retry logic, or framework-specific issues with Express, Next.js, or FastAPI.

跳到安装查看文件

仓库: hookdeck/webhook-skills
最近来源活动: 2026年2月6日 18:56
检测到的 SKILL.md 语言: 英语
星标: 89
分支: 14

安装方式

默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。

用 AI 助手安装

复制这段 Prompt，发给你正在使用的 AI 助手。

Follow https://skillsmp.com/skill-install/prompt.md to install only the Agent Skill at https://github.com/hookdeck/webhook-skills/tree/main/skills/webhook-handler-patterns.

直接命令不会经过审查 Prompt；运行前请先检查来源。

npx skills add https://github.com/hookdeck/webhook-skills --skill webhook-handler-patterns

命令会保持在同一行。复制前请横向滚动并检查完整内容。

想先保存到本地？可下载 SkillsMP 当前能够提供的文件。

检查来源文件

决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。

文件资源管理器

8 个文件

SKILL.md

来源说明 · 只读预览

name: webhook-handler-patterns
description: Best practices for webhook handlers. Use when implementing the handler sequence (verify first, parse second, handle idempotently), idempotency, error handling, retry logic, or framework-specific issues with Express, Next.js, or FastAPI.
license: MIT
metadata: {"author":"hookdeck","version":"0.1.0","repository":"https://github.com/hookdeck/webhook-skills"}

# Webhook Handler Patterns ## When to Use This Skill - Following the correct webhook handler order (verify → parse → handle idempotently) - Implementing idempotent webhook handlers - Handling errors and configuring retry behavior - Understanding framework-specific gotchas (raw body, middleware order) - Building production-ready webhook infrastructure ## Resources ### Handler Sequence - [references/handler-sequence.md](references/handler-sequence.md) - Verify first, parse second, handle idempotently third ### Best Practices - [references/idempotency.md](references/idempotency.md) - Prevent duplicate processing - [references/error-handling.md](references/error-handling.md) - Return codes, logging, dead letter queues - [references/retry-logic.md](references/retry-logic.md) - Provider retry schedules, backoff patterns ### Framework Guides - [references/frameworks/express.md](references/frameworks/express.md) - Express.js patterns and gotchas - [references/frameworks/nextjs.md](references/frameworks/nextjs.md) - Next.js App Router patterns - [references/frameworks/fastapi.md](references/frameworks/fastapi.md) - FastAPI/Python patterns ## Quick Reference ### Handler Sequence 1. **Verify signature first** — Use raw body; reject invalid requests with 4xx. 2. **Parse payload second** — After verification, parse or construct the event. 3. **Handle idempotently third** — Check event ID, then process; return 2xx for duplicates. See [references/handler-sequence.md](references/handler-sequence.md) for details and links to provider verification and idempotency patterns. ### Response Codes | Code | Meaning | Provider Behavior | |------|---------|-------------------| | `2xx` | Success | No retry | | `4xx` | Client error | Usually no retry (except 429) | | `5xx` | Server error | Retry with backoff | | `429` | Rate limited | Retry after delay | ### Idempotency Checklist 1. Extract unique event ID from payload 2. Check if event was already processed 3. Process event within transaction 4. Store event ID after successful processing 5. Return success for duplicate events ## Related Skills - [stripe-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/stripe-webhooks) - Stripe payment webhook handling - [shopify-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/shopify-webhooks) - Shopify e-commerce webhook handling - [github-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/github-webhooks) - GitHub repository webhook handling - [resend-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/resend-webhooks) - Resend email webhook handling - [chargebee-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/chargebee-webhooks) - Chargebee billing webhook handling - [clerk-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/clerk-webhooks) - Clerk auth webhook handling - [elevenlabs-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/elevenlabs-webhooks) - ElevenLabs webhook handling - [openai-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/openai-webhooks) - OpenAI webhook handling - [paddle-webhooks](https://github.com/hookdeck/webhook-skills/tree/main/skills/paddle-webhooks) - Paddle billing webhook handling - [hookdeck-event-gateway](https://github.com/hookdeck/webhook-skills/tree/main/skills/hookdeck-event-gateway) - Webhook infrastructure that replaces your queue — guaranteed delivery, automatic retries, replay, rate limiting, and observability for your webhook handlers

在 GitHub 查看

返回搜索返回安装

sentry-webhooks

Receive and verify Sentry webhooks (sentry.io — the error-monitoring and application-performance platform). Use when setting up a Sentry Integration Platform webhook handler for an internal or public integration, debugging Sentry-Hook-Signature verification, or handling events like issue.created, issue.resolved, event_alert.triggered, metric_alert.critical, error.created, comment.created, seer.pr_created or preprod_artifact.size_analysis_completed. Sentry signs with HMAC-SHA256 over the RAW body, lowercase hex, keyed with the integration's Client Secret, and sends the digest as Sentry-Hook-Signature (or Sentry-App-Signature on UI-component requests). The resource is only in the Sentry-Hook-Resource header — the body has no event/type field. Not Sentry Insurance (sentry.com), not @sentry/* SDK event ingest.

2026-10-02

pagerduty-webhooks

Receive and verify PagerDuty V3 webhooks (outbound webhook subscriptions created via the /webhook_subscriptions REST API). Use when setting up a PagerDuty webhook handler, debugging X-PagerDuty-Signature verification, or handling events like incident.triggered, incident.acknowledged, incident.resolved, incident.reassigned, incident.priority_updated, incident.annotated, incident.responder.added or service.updated. PagerDuty signs with HMAC-SHA256 over the RAW body, lowercase hex (Base16), in the X-PagerDuty-Signature header, which can carry MULTIPLE comma-separated `v1=` signatures for zero-downtime secret rotation. There is no timestamp and no replay window. Not PagerDuty Events API v1/v2 (that is inbound to PagerDuty), not V1/V2 webhook extensions, not PagerTree, not Pagerly, not Opsgenie, not incident.io.

2026-10-02

polytomic-webhooks

Receive and authenticate Polytomic webhooks. Use when building a Polytomic Webhook *destination* receiver, because Polytomic does NOT sign its payloads — there is NO signature, NO HMAC and NO signing secret, and the only authentication is a static shared bearer token compared against the connection Secret. Use when the `Polytomic-Signature-Timestamp` header misleads you into writing an HMAC verifier (it carries only an RFC 3339 timestamp, not a digest), when handling the single `sync.records` event, when looping over the `object.records[]` batch and its `hash` / user-defined `fields` keys, when deciding what `object.metadata` may be, or when a non-2xx response makes a Polytomic Model Sync appear as a failure.

2026-10-02

查看这个仓库的全部 Skills

webhook-handler-patterns

来源信息

安装方式

用 AI 助手安装

检查来源文件

同仓库更多 Skills

用 AI 助手安装

同仓库更多 Skills