---
title: "Store each incoming webhook before you act · Agent Wranglers"
url: https://agentwranglers.se/playbook/events/webhooks/store-incoming-webhooks
id: EVT-28
level: Recommended
updated: 2026-10-27
build: a2a6bdfed830
tokens: 1225
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Store each incoming webhook before you act on it

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Webhooks](https://agentwranglers.se/playbook/events/webhooks.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-27.

- ID: EVT-28
- Level: Recommended
- Chapter: [Webhooks](https://agentwranglers.se/playbook/events/webhooks.md)
- Rule: When a provider sends you a webhook, verify its signature, store the raw body and headers, and answer 2xx. Process the stored copy in a background job.
- Check: With the job worker stopped, send a signed test event. The handler answers 2xx within 1 second and one row holds the raw body. Send it again, and still one row exists. Start the worker, and the event is processed once.
- How: A provider waits only seconds for an answer and retries on a timeout, so slow work in the handler makes duplicates. Verify first, as [Sign every webhook](https://agentwranglers.se/playbook/events/webhooks/signed-webhooks.md) describes for both sides. Then insert the event under a unique constraint on the provider's event ID, so a retry inserts nothing. A job processes it as [Process each message once](https://agentwranglers.se/playbook/events/consuming-events/idempotent-consumers.md) says. The stored copy lets you replay an event after a bug fix, and shows support what arrived. Keep stored bodies only as long as the [retention schedule](https://agentwranglers.se/playbook/compliance/records-and-data-map/retention-schedule.md) allows, since they often hold personal data. Payment providers add a sweep for missed events, as [Sweep for missed events every hour](https://agentwranglers.se/playbook/payments/payment-events-and-reconciliation/missed-event-sweep.md) shows. Email and text providers send delivery events the same way.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### JavaScript example

```js
app.post('/hooks/payments', express.raw({ type: 'application/json' }), async (req, res) => {
  if (!isValidWebhook(req.headers, req.body, PAYMENT_WEBHOOK_SECRET)) return res.sendStatus(401);
  const event = JSON.parse(req.body);
  await db.query(
    'INSERT INTO incoming_webhooks (provider, event_id, body, received_at) VALUES ($1, $2, $3, now()) ON CONFLICT DO NOTHING',
    ['payments', event.id, req.body.toString('utf8')]);
  await queue.add('process-webhook', { provider: 'payments', eventId: event.id }, { jobId: `payments:${event.id}` });
  res.sendStatus(204);
});
```

### Python example

```python
@app.post("/hooks/payments", status_code=204)
async def payment_webhook(request: Request):
    raw = await request.body()
    if not is_valid_webhook(request.headers, raw, PAYMENT_WEBHOOK_SECRET):
        raise HTTPException(status_code=401)
    event = json.loads(raw)
    db.execute(
        "INSERT INTO incoming_webhooks (provider, event_id, body, received_at) VALUES (%s, %s, %s, now())"
        " ON CONFLICT DO NOTHING", ("payments", event["id"], raw.decode()))
    queue.enqueue(process_webhook, "payments", event["id"], job_id=f"payments:{event['id']}")
```

## Sources

- [Stripe webhooks, quickly return a 2xx response](https://docs.stripe.com/webhooks)

## Related rules

- EML-73 [Accept bounce and complaint events only when signed](https://agentwranglers.se/playbook/email/bounces-and-complaints/verify-delivery-events.md) in Email
- EVT-25 [Sign every webhook](https://agentwranglers.se/playbook/events/webhooks/signed-webhooks.md) in Integration and events
- EVT-11 [Process each message once](https://agentwranglers.se/playbook/events/consuming-events/idempotent-consumers.md) in Integration and events
- CMP-11 [Keep one retention schedule](https://agentwranglers.se/playbook/compliance/records-and-data-map/retention-schedule.md) in Compliance and governance
- PAY-20 [Sweep for missed events every hour](https://agentwranglers.se/playbook/payments/payment-events-and-reconciliation/missed-event-sweep.md) in Payments and billing

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/events/webhooks/store-incoming-webhooks">Agent Wranglers integration and events playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Retry until the receiver accepts](https://agentwranglers.se/playbook/events/webhooks/webhook-retries.md)
- Next: [Let customers test and inspect their webhook endpoints](https://agentwranglers.se/playbook/events/webhooks/webhook-endpoint-tools.md)
- [Webhooks](https://agentwranglers.se/playbook/events/webhooks.md)