webhook-setup

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.