Agent WranglersWebhooks and events
Sign every webhook, retry until it is accepted, and let receivers handle duplicates and out-of-order events without double work.
- Required 4
- Recommended 2
Required
Sign every webhook
RequiredSign 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
RequiredTreat any answer other than 2xx as a failure, and retry with growing gaps for a documented time.
Make receivers idempotent
RequiredGive every event a unique ID, and make receivers ignore an ID they have already processed.
Check webhook addresses before sending
RequiredAccept only public HTTPS addresses as webhook targets, and never let a webhook reach your internal network.
Recommended
Don't rely on event order
RecommendedInclude a timestamp or sequence number in every event, and let receivers fetch the current state instead of trusting arrival order.
Version event payloads
RecommendedName each event type and version its payload, and change it only by adding fields, as with the API itself.
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.