Five mistakes teams make with webhooks

We end up explaining this on discovery calls often enough that it deserved writing down. These are the ones we run into repeatedly when we audit webhooks.

Code gets read far more often than it gets written, and usually by someone with less context than the author had. Most teams find the first pass takes an afternoon and the maintenance takes minutes a month.

The mistakes we see most

• Treating it as a launch task rather than an ongoing one
• Assuming someone else already owns it
• Webhooks replace polling with something closer to real time
• Always verify the signature before trusting a payload
• Never checking whether the fix actually worked

Assume delivery can repeat and design for it. None of that requires a large budget, only a decision and someone to own it. Write the reasoning down alongside the decision, because the reasoning is what changes first.

Where to go from here

In practice

Most development decisions are really maintenance decisions wearing a different hat. 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

If you are not sure where your systems currently stand on this, it takes us about an hour to find out.