Webhook recipes: verify, deduplicate, act

Webhook hygiene: signature verification and idempotent consumers

Every recipe on this page sits on the same three-step spine, and the order is not negotiable. Verify the signature first, on the raw request body, before any parsing happens — an unsigned or badly signed request is not a shipping event, it is arbitrary input from the internet addressed to an endpoint that can move state in your systems. GoatLabels webhooks are signed for exactly this reason. Compare the computed signature to the received one in constant time, and treat verification failure as a hard reject, not a log line. The precise header names and algorithm belong to the API contract, so read them from the API docs rather than hard-coding what a tutorial — including this one — remembers them to be.

Second habit: deduplicate by event id. Deliveries can arrive more than once — a timeout on your side followed by a retry is the everyday case — so the consumer records each event id it has processed and drops repeats on arrival. One table, one unique index, one existence check. Third habit: make the action itself idempotent anyway. Set the order's state to fulfilled rather than toggling it; upsert the accounting entry keyed on the event id rather than appending blindly. Belt and braces, because the one duplicate that matters is the one that arrives the week your dedupe table was being migrated.

Recipe: adjustment event to accounting entry, end to end

This is the highest-value consumer most sellers never build. A carrier that reweighs or remeasures a parcel after acceptance bills the difference later — what those rebills are, how each carrier detects them, and how to dispute one is the carrier billing adjustments page's territory. What matters here is the shape of the moment: money left your business days or weeks after the sale it belongs to, and in most bookkeeping setups nobody finds out until month end, when the wallet history and the ledger disagree by a number no one can explain.

The recipe closes that gap to minutes. GoatLabels posts each adjustment as its own record, and the shipment.adjustment.created event delivers it to your endpoint carrying the wallet delta — the signed amount by which your prepaid balance actually changed. The consumer verifies, dedupes, then writes one accounting entry: the delta against your postage cost account, keyed to the original order so the order's true margin updates too. Book it on the date the event arrived, because that is when the money moved. One edge case belongs in the handler from day one: when an adjustment exceeds the wallet balance, the remainder is charged to the card on file, so let the entry reflect where the money actually came from rather than assuming the wallet absorbed all of it.

Recipe: label purchase to order-system fulfillment update

The second recipe kills the copy-paste step between buying a label and telling everything else about it. When a label purchase event arrives, the consumer looks up the order by your own reference, writes the tracking number and carrier onto it, and moves it to fulfilled — the same three edits a person makes by hand, minus the person. Because the write is an upsert keyed on the shipment, a retried delivery re-applies the same state instead of appending a second tracking number, which is the difference between an idempotent consumer and a support ticket.

What you should not rebuild is the buyer-facing half. GoatLabels already sends branded tracking emails and hosts a branded tracking page per shipment, so the consumer's job is internal state — your order system, your warehouse queue, your support tool's timeline — not re-notifying the buyer. Where this pattern earns its keep is volume: a store syncing hundreds of orders a day cannot afford a human between the label printer and the order system, and an event-driven consumer is how the two stay agreed without one.

Retries, outages, and replay: building a consumer that survives them

The uncomfortable truth about any webhook integration — every provider, not just this one — is that your endpoint will eventually be down while something important happens. Deploys, expired certificates, a cloud region having a bad afternoon. Two design rules make that survivable. First, acknowledge fast: accept the verified event, queue it durably, and return success in milliseconds, doing the slow work — database writes, third-party calls — off the request path, so your own latency never turns a healthy delivery into a retry storm.

Second, reconcile: run a periodic job that lists recent shipments and adjustments over the REST API and repairs anything your event log missed. Calls are unlimited on every plan, so the backstop poll costs nothing but the cron entry, and the delivery and retry contract itself is documented in the API docs — build against that, not against assumptions. Webhooks for freshness, reconciliation for certainty is the architecture that survives an outage without a human replaying anything by hand. It is also, not coincidentally, the pattern that makes switching costs low: consumers built this way are what API developers comparing platforms and teams pricing per-call APIs end up porting in an afternoon.