webhook-design

Designs webhook delivery systems with retries, HMAC signatures, and idempotency handling.

1|Updated Mar 21, 2026
One-click install
npx skills add https://github.com/kalilurrahman/kr-claudiator-skills-original-prompts --skill webhook-design-kalilurrahman
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: webhook-design
Source: https://github.com/kalilurrahman/kr-claudiator-skills-original-prompts/tree/main/01-software-dev/webhook-design
Command: npx skills add https://github.com/kalilurrahman/kr-claudiator-skills-original-prompts --skill webhook-design-kalilurrahman

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Building webhook systems that reliably deliver events to subscriber endpoints is hard: messages get lost, retries cause duplicates, and unsigned payloads are spoofable. This Skill guides the design of a complete webhook delivery pipeline covering event schemas, async queues, retry policies, and signature verification. ## Core Features & Use Cases - Event & Payload Design: Defines naming conventions (resource.action), JSON payload schemas with event_id, api_version, and previous_attributes for update events. - Delivery Pipeline: Implements a publisher, queue-based delivery worker, exponential backoff with jitter (5 attempts), and dead letter queue for persistent failures. - Security & Idempotency: Generates HMAC-SHA256 signatures, subscriber-side verification with constant-time comparison, event ID deduplication, HTTPS-only URLs, and IP allowlisting. - Use Case: You are adding webhooks to a payments platform. Use this Skill to produce the event catalog, delivery worker code, subscription management API, delivery log schema, and Prometheus monitoring metrics. ## Quick Start Ask the AI to design a webhook system for your application with order and payment events, at-least-once delivery, and HMAC signature verification.

Frequently Asked Questions about webhook-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I implement webhook retries with exponential backoff?

Use a delivery worker that catches failures and requeues the message with a delay of base^attempt seconds, capped at a maximum. Add jitter of about 20 percent to prevent thundering herd, and move messages to a dead letter queue after 5 attempts.

How do I verify webhook signatures in Python?

Compute an HMAC-SHA256 hash of the JSON payload using the shared secret, then compare it to the X-Webhook-Signature header using hmac.compare_digest. Constant-time comparison prevents timing attacks that could leak the valid signature.

How do I prevent duplicate webhook processing?

Include a unique event_id in every payload and have the subscriber track processed IDs in Redis with a 24-hour TTL. If an event_id was already processed, return 200 immediately without reprocessing, making the endpoint idempotent.

Should webhooks retry on 4xx errors?

No, 4xx client errors should not be retried because retrying will not fix a malformed request or authentication failure. Only retry on 5xx server errors and network exceptions, and log 4xx failures as final.

Why should webhook endpoints return 200 immediately?

Returning 200 immediately and processing asynchronously prevents slow business logic from causing delivery timeouts and unnecessary retries. The subscriber should acknowledge receipt first, then handle the event in a background job.