webhook-architecture

Implement webhook delivery with HMAC verification, retries, idempotent receivers, and a dead-letter queue.

14|3|Updated Mar 22, 2026
One-click install
npx skills add https://github.com/tomtoto757/ecomm-ai-skills-hub --skill webhook-architecture-tomtoto757
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: webhook-architecture
Source: https://github.com/tomtoto757/ecomm-ai-skills-hub/tree/main/skills/platform-integrations-infrastructure/finsilabs/integrations-apis/webhook-architecture
Command: npx skills add https://github.com/tomtoto757/ecomm-ai-skills-hub --skill webhook-architecture-tomtoto757

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Webhook deliveries can be lost, replayed, or spoofed, causing missed orders, duplicate processing, and operational toil. This Skill provides a clear architecture and implementation guidance to verify signatures, deduplicate events, retry failed deliveries, and surface unrecoverable failures for human intervention.

Core Features & Use Cases

  • Timing-safe HMAC verification for incoming providers (Shopify, Stripe) and outbound signing so recipients can authenticate deliveries.
  • Idempotent receivers that mark event IDs as received before processing to prevent duplicate work under retries.
  • Outbox pattern for sending with a poller, exponential backoff retry schedule (1m, 5m, 30m, 2h, 8h), SKIP-LOCKED-friendly polling, and dead-letter queue promotion with alerting and replay.
  • Operational tooling: delivery attempt logging, DLQ alerting, replay mechanisms, and platform-specific setup notes for Shopify, WooCommerce, and BigCommerce.
  • Use Case: Ensure Shopify order create events are verified, deduplicated, and processed exactly once even when the platform retries for 72 hours.

Quick Start

Set up an HTTPS endpoint that verifies the provider HMAC header, records the provider event ID as received, and enqueues the payload for asynchronous processing.

Frequently Asked Questions about webhook-architecture

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

FAQPage Schema
How do I prevent duplicate processing when receiving webhook retries from Shopify?

To prevent duplicate webhook processing, implement idempotent receivers that mark provider event IDs as received before processing, ensuring events are processed exactly once even when platforms retry deliveries for 72 hours.

How does HMAC signature verification work for incoming webhooks?

HMAC signature verification authenticates incoming webhook deliveries using timing-safe comparisons to validate provider headers, preventing spoofed events from platforms like Shopify or Stripe from being processed by your endpoint.

What is the best way to handle failed webhook deliveries and undeliverable events?

The best way to handle failed webhook deliveries is using an outbox pattern with an exponential backoff retry schedule (1m, 5m, 30m, 2h, 8h) and promoting undeliverable events to a dead-letter queue with alerting.

Does this webhook architecture support replay protection and dead-letter queue replay?

Yes, this webhook architecture supports replay protection through HMAC verification and provides operational tooling for dead-letter queue promotion with alerting and replay functionality to recover missed deliveries.

Can I use the outbox pattern for sending webhooks with custom event-driven services?

Yes, you can use the outbox pattern for sending webhooks with custom event-driven services, utilizing a poller with SKIP-LOCKED-friendly polling and exponential backoff retries to guarantee reliable outbound delivery.

Why do I need a dead-letter queue for my webhook delivery system?

You need a dead-letter queue to surface unrecoverable webhook delivery failures for human intervention, preventing lost orders and operational toil when automatic retries exhaust the exponential backoff schedule.