webhook-setup

name	webhook-setup
description	Set up webhook receivers with signature verification, idempotent event processing, retry handling, and dead letter queues for reliable event-driven integrations. Use when the user requests webhook setup or provides relevant inputs for this workflow.
license	MIT
metadata	{"author":"awesome-ai-agent-skills","version":"1.0.0"}

Webhook Setup

This skill enables an AI agent to build production-grade webhook receivers and configure webhook producers. The agent implements HTTP endpoints that accept event payloads, verify cryptographic signatures to authenticate senders, process events idempotently to handle retries safely, and route events by type to appropriate handlers. The result is a reliable event-driven integration that handles real-world failure modes including replay attacks, out-of-order delivery, and provider timeouts.

Workflow

1. Design the webhook endpoint: Create an HTTP POST endpoint at a stable, non-guessable URL path (e.g., /webhooks/stripe, /webhooks/github). The endpoint must return a 200 OK response quickly (within 5 seconds for most providers) to acknowledge receipt—long processing should be done asynchronously via a job queue. Use HTTPS exclusively; most providers reject plain HTTP endpoints.

2. Implement signature verification: Every webhook provider signs payloads using HMAC-SHA256, RSA, or a similar scheme. Before processing any event, verify the signature using the provider's signing secret. Compare signatures using a constant-time comparison function to prevent timing attacks. Reject requests with missing or invalid signatures immediately with a 401 Unauthorized response. Read the raw request body for verification—parsed JSON may differ from the signed bytes.

3. Parse and route events by type: Parse the verified payload and extract the event type (e.g., payment_intent.succeeded, push). Route each event type to a dedicated handler function using a registry or switch statement. Log unrecognized event types at warning level and return 200 OK to prevent the provider from retrying unhandled events indefinitely.

4. Process events idempotently: Providers retry webhook delivery when they don't receive a timely 200 response, which means your handler may receive the same event multiple times. Store processed event IDs in a database table and check for duplicates before processing. Use database transactions to atomically mark an event as processed and perform its side effects.

5. Add async processing and dead letter queues: For events that require heavy processing (sending emails, updating multiple records), acknowledge the webhook immediately and enqueue the event for background processing. Failed events that exhaust retries should be moved to a dead letter queue (DLQ) for manual inspection. Set up monitoring and alerts on DLQ depth.

6. Configure the webhook on the provider side: Register your endpoint URL with the webhook provider, select the event types you need (subscribe to the minimum set), and note the signing secret. Test the webhook using the provider's test/ping functionality. Set up monitoring for delivery failures on the provider dashboard.

Supported Technologies

• Web frameworks: Express.js, Fastify, Flask, FastAPI, Django, Rails, Spring Boot
• Queue systems: Bull/BullMQ (Redis), Celery (Python), Sidekiq (Ruby), SQS, RabbitMQ
• Providers: Stripe, GitHub, Slack, Twilio, SendGrid, Shopify, PayPal, Paddle
• Monitoring: Svix (webhook infrastructure), Hookdeck, ngrok (local development)
• Databases: PostgreSQL, MySQL, Redis (for idempotency tracking)

Usage

Provide the agent with the webhook provider (Stripe, GitHub, etc.), the events you want to handle, and your server framework. The agent will produce a complete webhook receiver with signature verification, event routing, idempotent processing, and error handling. For local development, the agent can set up ngrok or a similar tunnel for testing.

Examples

Example 1: Stripe Webhook Receiver (Express.js)

const express = require("express");
const crypto = require("crypto");
const { Queue } = require("bullmq");

const app = express();
const eventQueue = new Queue("webhook-events", { connection: { host: "localhost" } });

// CRITICAL: Use raw body for signature verification — must be before json parser
app.post("/webhooks/stripe", express.raw({ type: "application/json" }), async (req, res) => {
  const signature = req.headers["stripe-signature"];
  const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET;

  // Step 1: Verify signature
  let event;
  try {
    event = verifyStripeSignature(req.body, signature, webhookSecret);
  } catch (err) {
    console.error(`Signature verification failed: ${err.message}`);
    return res.status(401).json({ error: "Invalid signature" });
  }

  
   alreadyProcessed =  (event.);
   (alreadyProcessed) {
    .();
     res.().({ : , :  });
  }

  
   {
     eventQueue.(event., {
      : event.,
      : event.,
      : event..,
      : event.,
    });
     (event.);
    res.().({ :  });
  }  (err) {
    .(, err);
    res.().({ :  });
  }
});


 () {
   elements = signatureHeader.().( {
     [key, value] = part.();
    acc[key.()] = value;
     acc;
  }, {});

   timestamp = elements[];
   expectedSig = elements[];

  
   tolerance = ; 
   currentTime = .(.() / );
   (currentTime - (timestamp) > tolerance) {
      ();
  }

  
   signedPayload = ;
   computedSig = crypto
    .(, secret)
    .(signedPayload)
    .();

  
   (!crypto.(.(expectedSig), .(computedSig))) {
      ();
  }

   .(payload);
}


 {  } = ();
 db =  ();

  () {
   result =  db.(
    ,
    [eventId]
  );
   result.. > ;
}

  () {
   db.(
    ,
    [eventId]
  );
}


 {  } = ();

 worker =  (,  (job) => {
   { eventId, type, data } = job.;

   handlers = {
    : handlePaymentSucceeded,
    : handlePaymentFailed,
    : handleSubscriptionCanceled,
    : handleInvoicePaymentFailed,
  };

   handler = handlers[type];
   (!handler) {
    .();
    ;
  }

   (data, eventId);
   db.(, [eventId]);
}, { : { :  } });

  () {
   orderId = paymentIntent..;
   db.(, [
    paymentIntent., orderId,
  ]);
  .();
}

  () {
   orderId = paymentIntent..;
   db.(, [orderId]);
  
  .();
}

  () {
   db.(, [
    subscription.,
  ]);
}

  () {
  .();
}

app.(,  .());

Example 2: GitHub Webhook for CI Triggers (Python/FastAPI)

import hashlib
import hmac
import os
import logging
from datetime import datetime, timezone
from fastapi import FastAPI, Request, HTTPException, BackgroundTasks
from pydantic import BaseModel

app = FastAPI()
logger = logging.getLogger(__name__)

GITHUB_WEBHOOK_SECRET = os.environ["GITHUB_WEBHOOK_SECRET"]

# In-memory idempotency store (use Redis or PostgreSQL in production)
processed_deliveries: set[str] = set()


def verify_github_signature(payload_body: bytes, signature_header: str | None) -> None:
    """Verify the GitHub webhook signature using HMAC-SHA256."""
    if not signature_header:
        raise HTTPException(status_code=401, detail="Missing X-Hub-Signature-256 header")

    expected_signature = "sha256=" + hmac.new(
        GITHUB_WEBHOOK_SECRET.encode(),
        payload_body,
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(expected_signature, signature_header):
        raise HTTPException(status_code=401, detail="Invalid webhook signature")


@app.post("/webhooks/github")
async def github_webhook(request: Request, background_tasks: BackgroundTasks):
    # Step 1: Read raw body and verify signature
    body =  request.body()
    signature = request.headers.get()
    verify_github_signature(body, signature)

    
    delivery_id = request.headers.get()
     delivery_id  processed_deliveries:
        logger.info()
         {: , : delivery_id}

    
    event_type = request.headers.get()
    payload =  request.json()

    logger.info()

    
    processed_deliveries.add(delivery_id)
    background_tasks.add_task(process_github_event, event_type, payload, delivery_id)

     {: , : event_type, : delivery_id}


  ():
    
    handlers = {
        : handle_push,
        : handle_pull_request,
        : handle_issue,
        : handle_ping,
    }

    handler = handlers.get(event_type)
      handler:
        logger.warning()
        

    :
         handler(payload)
        logger.info()
     Exception  e:
        logger.error()
        
        


  ():
    
    ref = payload.get(, )
    repo = payload[][]
    commits = payload.get(, [])

     ref != :
        logger.info()
        

    commit_messages = [c[].split()[]  c  commits]
    logger.info()

    
    changed_files = ()
     commit  commits:
        changed_files.update(commit.get(, []))
        changed_files.update(commit.get(, []))

    
     (f.startswith()  f  changed_files):
         trigger_ci_pipeline(repo, , payload[])
     (f.startswith()  f  changed_files):
         trigger_ci_pipeline(repo, , payload[])

    logger.info()


  ():
    
    action = payload[]
    pr = payload[]
    repo = payload[][]

     action  (, ):
        logger.info()
         trigger_ci_pipeline(repo, , pr[][])
     action ==   pr.get():
        logger.info()
         trigger_ci_pipeline(repo, , pr[])


  ():
    
    action = payload[]
    issue = payload[]
    logger.info()


  ():
    
    logger.info()


  ():
    
    logger.info()
    

Best Practices

• Respond quickly, process later. Return 200 OK within 3-5 seconds. Most providers time out at 10-30 seconds and will retry, causing duplicate processing. Enqueue events into a background job queue for actual processing.
• Always verify signatures before processing any webhook payload. Use the provider's signing secret and a constant-time comparison function. Never skip verification, even in development.
• Implement idempotency with event IDs. Store the provider's delivery/event ID in a database and check for duplicates before processing. Use INSERT ... ON CONFLICT DO NOTHING for atomic deduplication.
• Use a dead letter queue for events that fail processing after all retries. Monitor DLQ depth and set up alerts. Provide tooling to replay events from the DLQ after fixing bugs.
• Subscribe only to events you handle. Receiving events you don't process wastes bandwidth and creates noise in logs. Most providers let you select specific event types during webhook configuration.
• Protect against replay attacks by checking the event timestamp. Reject events older than 5 minutes (configurable based on your tolerance). Stripe, GitHub, and most providers include a timestamp in the signature header for this purpose.

Edge Cases

• Out-of-order delivery: Webhooks can arrive out of order (e.g., invoice.paid before invoice.created). Use event timestamps and the resource's current state (fetched via API) to make decisions rather than assuming sequential delivery.
• Provider retries during deployments: If your server is down during a deployment, the provider will retry. Ensure your idempotency logic handles receiving the same event after your server recovers. Use rolling deployments so at least one instance is always available.
• Payload size limits: Some providers send large payloads (especially for diff-heavy GitHub push events). Set appropriate body size limits on your endpoint (e.g., 10MB) and handle 413 Payload Too Large gracefully.
• Secret rotation: When rotating webhook signing secrets, support both the old and new secrets during the transition period. Verify against the new secret first, falling back to the old secret. Remove the old secret after confirming all deliveries use the new one.
• Endpoint URL changes: If you need to change your webhook URL, register the new URL before deregistering the old one. Run both endpoints in parallel until the provider confirms deliveries to the new URL succeed.
• Testing locally: Use ngrok, Cloudflare Tunnel, or the provider's CLI (e.g., stripe listen --forward-to localhost:3000/webhooks/stripe) to forward webhooks to your local development server.