home / skills / jeremylongshore / claude-code-plugins-plus-skills / creating-webhook-handlers

creating-webhook-handlers skill

safe

/plugins/api-development/webhook-handler-creator/skills/creating-webhook-handlers

This skill helps you create robust webhook handlers with signature verification, retry logic, and payload validation across frameworks.

npx playbooks add skill jeremylongshore/claude-code-plugins-plus-skills --skill creating-webhook-handlers

Review the files below or copy the command above to add this skill to your agents.

Files (4)

SKILL.md

2.4 KB

---
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".
  
allowed-tools: Read, Write, Edit, Grep, Glob, Bash(api:webhook-*)
version: 1.0.0
author: Jeremy Longshore <[email protected]>
license: MIT
---

# Creating Webhook Handlers

## Overview


This skill provides automated assistance for webhook handler creator tasks.
This skill provides automated assistance for the described functionality.

## Prerequisites

Before using this skill, ensure you have:
- API design specifications or requirements documented
- Development environment with necessary frameworks installed
- Database or backend services accessible for integration
- Authentication and authorization strategies defined
- Testing tools and environments configured

## Instructions

1. Use Read tool to examine existing API specifications from {baseDir}/api-specs/
2. Define resource models, endpoints, and HTTP methods
3. Document request/response schemas and data types
4. Identify authentication and authorization requirements
5. Plan error handling and validation strategies
1. Generate boilerplate code using Bash(api:webhook-*) with framework scaffolding
2. Implement endpoint handlers with business logic
3. Add input validation and schema enforcement
4. Integrate authentication and authorization middleware
5. Configure database connections and ORM models
1. Write integration tests covering all endpoints


See `{baseDir}/references/implementation.md` for detailed implementation guide.

## Output

- `{baseDir}/src/routes/` - Endpoint route definitions
- `{baseDir}/src/controllers/` - Business logic handlers
- `{baseDir}/src/models/` - Data models and schemas
- `{baseDir}/src/middleware/` - Authentication, validation, logging
- `{baseDir}/src/config/` - Configuration and environment variables
- OpenAPI 3.0 specification with complete endpoint definitions

## Error Handling

See `{baseDir}/references/errors.md` for comprehensive error handling.

## Examples

See `{baseDir}/references/examples.md` for detailed examples.

## Resources

- Express.js and Fastify for Node.js APIs
- Flask and FastAPI for Python APIs
- Spring Boot for Java APIs
- Gin and Echo for Go APIs
- OpenAPI Specification 3.0+ for API documentation

Overview

This skill helps you create robust webhook endpoints with signature verification, retry logic, and payload validation. It guides you from API design through implementation, testing, and documentation. The goal is secure, reliable webhook processing ready for production use.

How this skill works

It inspects API specifications and resource models, scaffolds endpoint routes and controllers, and generates middleware for authentication and validation. It implements signature verification, idempotency or deduplication, and retry handling for transient failures. It also produces OpenAPI definitions and test scaffolding so handlers are documented and verifiable.

When to use it

Receiving third-party event notifications (payment gateways, CI systems, SaaS webhooks)
Building new webhook endpoints to integrate external services
Hardening existing webhook handlers with security and retry behavior
Preparing webhook handlers for high-throughput or unreliable networks

Best practices

Verify signatures on every incoming request and reject invalid payloads immediately
Validate payload schemas against documented request models before business logic runs
Implement idempotency or deduplication to avoid double-processing events
Use exponential backoff and limited retries for transient failures; log and escalate persistent failures
Document endpoints in OpenAPI and include example payloads and error responses

Example use cases

Implement a payment webhook that verifies HMAC signatures, persists events, and retries on DB conflicts
Create a deployment webhook that validates payload schema and triggers CI jobs with retry and rate limiting
Add middleware to existing API to validate webhook payloads, check auth tokens, and enforce idempotency keys
Generate Python FastAPI handlers with Pydantic models, middleware for signature checks, and integration tests

FAQ

Which frameworks are recommended?

Use frameworks that support middleware and schema validation: FastAPI or Flask for Python, Express or Fastify for Node.js. Choose based on your team's expertise and deployment environment.

How should I handle retries from providers?

Respond quickly with appropriate HTTP status codes, implement idempotency or deduplication, and use exponential backoff for internal retries. Log retry attempts and surface persistent failures to alerts.