A short guide to webhooks

This is one of those topics that looks small until it costs you something. Everything we would tell a client about webhooks in the time it takes to drink a coffee.

Code gets read far more often than it gets written, and usually by someone with less context than the author had. The teams that stay on top of it are the ones who put it on a calendar rather than a wish list.

Why this earns attention

Webhooks replace polling with something closer to real time. The cost of getting this wrong is rarely visible on the day it happens. The teams that stay on top of it are the ones who put it on a calendar rather than a wish list.

How to approach it

Always verify the signature before trusting a payload. Where this goes wrong is almost never a lack of knowledge. Assume whoever inherits this will have half your context and none of your patience.

The mistakes we see most

Assume delivery can repeat and design for it. The teams that handle this well are rarely the ones with the biggest budgets. The failure mode is not doing it wrong, it is doing it once and assuming it stays done.

What this looks like day to day

The question is rarely whether something can be built, but what it costs to keep running afterwards. Three things worth confirming about webhooks before you move on:

• Someone can say what the current setup is without going to look
• Webhooks replace polling with something closer to real time — and you know whether that is true here
• There is a way to tell whether the last change to this helped

Pick the one that would hurt most if it failed, and start there.