webhook-deliverylisted

# Webhook Delivery Webhooks are the highest-leverage trust surface a developer tool has: they run inside the *customer's* infrastructure, and every flake is a support ticket on their side. The bar is Stripe. This skill gets a design to that bar without a year of incidents teaching it the hard way. ## Before you start Check for `.agents/devtool-context.md` and read it if present (it tells you the API shape, stack, and scale, all of which change the design). If absent, ask: 1. What events would customers subscribe to, and what triggers them? 2. Expected volume: tens a day or thousands a second? 3. Build vs. buy appetite: is a hosted sender (Svix, Hookdeck) on the table, or is this in-house? On build vs. buy: below serious scale, Svix is the correct default answer; Clerk, Resend, and Brex ship webhooks this way. Recommend it unless the user has a real reason (data locality, cost at volume, it *is* their product). If they buy, skip to the envelope and consumer-docs sections. Those decisions remain theirs either way. ## The design, in order of consequence Work through these with the user and produce a written design doc plus schema/code artifacts as you go. Positions below are defaults; deviate only with a reason. ### 1. Event envelope Every event shares one envelope. Design it once, version it forever: ```json { "id": "evt_7f3a2b9c1d", "type": "invoice.paid", "api_version": "2026-08-01", "occurred_at": "2026-08-10T12:00:00Z", "data": { "object": { /* the resou