---
type: "article"
title: "Webhooks are a distributed systems problem in a trenchcoat"
summary: "Retries, ordering, idempotency, signatures. The word 'webhook' hides four hard problems."
newsletter: "API Bytes"
newsletter_handle: "api-bytes"
newsletter_url: "https://staging.in.usecommune.com/n/api-bytes"
author: "Fran Méndez (@fmvilas)"
published: "2026-07-23T08:30:00.000Z"
canonical_url: "https://staging.in.usecommune.com/n/api-bytes/a/webhooks-are-hard"
markdown_url: "https://staging.in.usecommune.com/n/api-bytes/a/webhooks-are-hard.md"
chat_url: "https://staging.in.usecommune.com/n/api-bytes/a/webhooks-are-hard/chat"
body_source: "native"
likes: 5
replies: 0
body_words: 58
---

# Webhooks are a distributed systems problem in a trenchcoat

'Just send a webhook' is the four most underestimated words in API design.

- Retries mean the receiver must be idempotent.
- At-least-once delivery means duplicates are normal, not a bug.
- Signatures aren't optional the moment money is involved.

Ship the signing secret and an idempotency key from day one. Retrofitting them is a migration nobody enjoys.

***

## Discussion

No replies yet.