Reading webhook payloads when the clock is ticking
A calm, repeatable way to inspect Stripe-style or custom webhook JSON during an incident — what to check first, what to ignore, and how to compare retries.
Someone pings you because payments, notifications, or sync jobs are failing. The vendor dashboard shows retries. Your logs show a 500. The webhook body is a wall of nested objects. This is not the moment to admire a graph visualization. You need the event type, the resource id, and the field your handler actually reads — in that order.
Identify the event before you dig into nested data
Most webhook platforms put a type or event name near the top: invoice.paid, message.received, repo.push. Find that string first. If you do not know which handler should run, every nested field is noise. Paste the body, format it, and search for "type" or "event".
Next, grab the object id your system uses for idempotency — often data.object.id or a delivery id in the headers. Write those two values in the incident channel so the next person is not repeating your scroll.
Separate transport failure from business failure
If your endpoint returned 500, the vendor will retry. That can produce three nearly identical payloads with different delivery timestamps. Comparing two retries side by side tells you whether the body changed or whether your bug is simply deterministic. Unchanged bodies point at your handler. Changed bodies point at a race or a state update on the vendor side.
Do not rewrite the handler until you know which of those two stories you are in.
Watch for signature and encoding side quests
Sometimes the JSON is fine and the signature header is wrong, or the body was read as a string twice. Those bugs feel like JSON bugs because the parse step is where people look. If Validate passes and your unit tests with a fixture pass, check middleware that consumes the raw body before JSON.parse.
Keep a sanitized fixture of a real payload in the repo — secrets removed — so the next incident is not the first time someone sees the shape.
A minimal kit for the on-call laptop
You need a place to paste, validate, format, and optionally compare. View My JSON covers that in the browser without installing another desktop app during a fire. Use Tree when the resource is deep. Use Table when the payload includes a list of line items. Use Compare when two retries disagree.
After the incident, turn the fixture into a regression test. The viewer helped you see; the test keeps it from returning.