About

Imported from jeremylongshore/tons-of-skills-marketplace (plugins/api-development/webhook-handler-creator/skills/creating-webhook-handlers/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill creating-webhook-handlers. Copyright stays with the author (MIT).

Creating Webhook Handlers

Name: creating-webhook-handlers
Author: jeremylongshore

Overview

Create secure webhook receiver endpoints with HMAC signature verification, idempotent event processing, and automatic retry handling. Support ingestion from providers like Stripe, GitHub, Twilio, and Slack with provider-specific signature validation schemes and payload parsing.

Prerequisites

Web framework with raw body access (Express with express.raw(), FastAPI with Request.body())
Webhook provider credentials: signing secret or shared secret key
Persistent storage for idempotency tracking (Redis or database table for processed event IDs)
Queue system for async processing (optional: Bull, Celery, SQS)
ngrok or similar tunnel for local development testing

Instructions

Examine existing route definitions and middleware using Grep and Read to identify where webhook endpoints integrate into the application.
Create a dedicated webhook route (e.g., POST /webhooks/:provider) that captures the raw request body before any JSON parsing middleware runs.
Implement HMAC-SHA256 signature verification by computing HMAC(raw_body, signing_secret) and comparing against the provider's signature header (X-Hub-Signature-256, Stripe-Signature, X-Twilio-Signature).
Add idempotency protection by storing processed event IDs (e.g., evt_xxx) in Redis or a database table, rejecting duplicates with 200 OK to prevent provider retries.
Parse the event type from the payload (event.type, action, EventType) and route to the appropriate handler function using a dispatch map.
Respond with 200 OK immediately, then enqueue the event payload for asynchronous processing to avoid webhook timeout failures.
Implement dead-letter handling for events that fail processing after maximum retry attempts, logging the full payload for manual inspection.
Write tests that replay recorded webhook payloads with valid and tampered signatures to verify acceptance and rejection behavior.

See ${CLAUDE_SKILL_DIR}/references/implementation.md for the full implementation guide.

Output

${CLAUDE_SKILL_DIR}/src/webhooks/receiver.js - Webhook endpoint with signature verification
${CLAUDE_SKILL_DIR}/src/webhooks/handlers/ - Per-event-type handler functions
${CLAUDE_SKILL_DIR}/src/webhooks/verify.js - HMAC signature verification utilities
${CLAUDE_SKILL_DIR}/src/webhooks/idempotency.js - Duplicate event detection logic
${CLAUDE_SKILL_DIR}/src/queues/webhook-processor.js - Async event processing queue worker
${CLAUDE_SKILL_DIR}/tests/webhooks/ - Replay tests with recorded payloads

Error Handling

Error	Cause	Solution
401 Signature Mismatch	HMAC verification failed against provider signature	Log the expected vs. received signature (redacted); verify signing secret rotation status
400 Malformed Payload	Raw body is not valid JSON or missing required fields	Return 400 so provider marks delivery as failed; log raw body for debugging
200 OK (duplicate)	Event ID already processed; idempotency guard triggered	Return 200 to prevent provider retry loops; log duplicate detection for monitoring
504 Gateway Timeout	Synchronous processing exceeded provider timeout (typically 5-30s)	Move processing to async queue; respond 200 immediately upon signature verification
500 Handler Exception	Business logic threw unhandled error during processing	Catch at dispatch layer; log full error with event payload; allow provider to retry

Refer to ${CLAUDE_SKILL_DIR}/references/errors.md for comprehensive error patterns.

Examples

Stripe payment webhook: Verify Stripe-Signature header using stripe.webhooks.constructEvent(), then dispatch payment_intent.succeeded to fulfill orders and charge.refunded to process refund credits.

GitHub push webhook: Validate X-Hub-Signature-256, parse push events, extract commit list, and trigger CI/CD pipeline via queue message.

Multi-provider router: Single /webhooks/:provider endpoint that loads provider-specific signature verifier and event schema from a registry, supporting Stripe, GitHub, Twilio, and custom providers.

See ${CLAUDE_SKILL_DIR}/references/examples.md for additional examples.

Resources

Stripe Webhook Signatures: https://stripe.com/docs/webhooks/signatures
GitHub Webhook Events: https://docs.github.com/en/webhooks
RFC 2104 HMAC specification for signature computation
OWASP Webhook Security best practices

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/jeremylongshore-tons-of-skills-marketplace-creating-webh-55da8a/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

jeremylongshore-tons-of-skills-marketplace-creating-webh-55da8a.ocm.jsonjson

{
  "ocm": "1",
  "id": "jeremylongshore-tons-of-skills-marketplace-creating-webh-55da8a",
  "kind": "skill",
  "name": "creating-webhook-handlers",
  "description": "Create webhook endpoints with signature verification, retry logic, and payload validation. Use when receiving and processing webhook events. Trigger with phrases like \"create webhook\", \"handle webhook events\", or \"setup webhook handler\".",
  "publisher": "jeremylongshore",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "general"
    ],
    "tags": [
      "skill-md",
      "api",
      "webhooks",
      "webhook-handlers",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Create webhook endpoints with signature verification, retry logic, and payload validation. Use when receiving and processing webhook events. Trigger with phrases like \"create webhook\", \"handle webhook events\", or \"setup webhook handler\"."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/jeremylongshore/tons-of-skills-marketplace",
      "path": "plugins/api-development/webhook-handler-creator/skills/creating-webhook-handlers/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/jeremylongshore/tons-of-skills-marketplace/blob/HEAD/plugins/api-development/webhook-handler-creator/skills/creating-webhook-handlers/SKILL.md",
      "key": "jeremylongshore/tons-of-skills-marketplace/plugins/api-development/webhook-handler-creator/skills/creating-webhook-handlers/SKILL.md"
    },
    "compatibility": "Designed for Claude Code",
    "allowed_tools": [
      "Read,",
      "Write,",
      "Edit,",
      "Grep,",
      "Glob,",
      "Bash(api:webhook-*)"
    ],
    "license": "MIT"
  },
  "instructions": "# Creating Webhook Handlers\n\n## Overview\n\nCreate secure webhook receiver endpoints with HMAC signature verification, idempotent event processing, and automatic retry handling. Support ingestion from providers like Stripe, GitHub, Twilio, and Slack with provider-specific signature validation schemes and payload parsing.\n\n## Prerequisites\n\n- Web framework with raw body access (Express with `express.raw()`, FastAPI with `Request.body()`)\n- Webhook provider credentials: signing secret or shared secret key\n- Persistent storage for idempotency tracking (Redis or database table for processed event ID",
  "cost": {
    "context_tokens": 1126
  }
}

Fetch it by URL: GET /api/v1/registry/jeremylongshore-tons-of-skills-marketplace-creating-webh-55da8a/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.