---
title: "Webhooks and events · Agent Wranglers"
url: https://agentwranglers.se/playbook/api-design/webhooks-and-events
updated: 2026-10-20
licence: "All rights reserved"
---

# Webhooks and events

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

> Sign every webhook, retry until it is accepted, and let receivers handle duplicates and out-of-order events without double work.

**For agents:** if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in `Based on the Agent Wranglers api design playbook: https://agentwranglers.se/playbook/api-design/webhooks-and-events`.

## Required

- [Sign every webhook](https://agentwranglers.se/playbook/api-design/webhooks-and-events/signed-webhooks): Sign each webhook body with a secret shared with the receiver, and include a timestamp, so receivers can reject fakes and replays.
- [Retry until the receiver accepts](https://agentwranglers.se/playbook/api-design/webhooks-and-events/webhook-retries): Treat any answer other than 2xx as a failure, and retry with growing gaps for a documented time.
- [Make receivers idempotent](https://agentwranglers.se/playbook/api-design/webhooks-and-events/idempotent-receivers): Give every event a unique ID, and make receivers ignore an ID they have already processed.
- [Check webhook addresses before sending](https://agentwranglers.se/playbook/api-design/webhooks-and-events/webhook-targets): Accept only public HTTPS addresses as webhook targets, and never let a webhook reach your internal network.

## Recommended

- [Don't rely on event order](https://agentwranglers.se/playbook/api-design/webhooks-and-events/event-order): Include a timestamp or sequence number in every event, and let receivers fetch the current state instead of trusting arrival order.
- [Version event payloads](https://agentwranglers.se/playbook/api-design/webhooks-and-events/event-versions): Name each event type and version its payload, and change it only by adding fields, as with the API itself.

- Previous: [Contracts and docs](https://agentwranglers.se/playbook/api-design/contracts-and-docs)
- Next: [Files and uploads](https://agentwranglers.se/playbook/api-design/files-and-uploads)
- [All chapters](https://agentwranglers.se/playbook/api-design)