Designing Idempotent Webhook Handlers for Crypto Payment Providers

Crypto payment providers retry webhooks. Your handler will see the same payment.confirmed event more than once, sometimes minutes apart, sometimes after a deploy. If fulfilment is not idempotent, you double-ship digital goods or double-credit wallets.

Use the provider event id as the dedupe key

Persist event_id (or the equivalent) in a unique-indexed table before you fulfil. If the insert conflicts, return 200 and stop. Do not fulfil first and log later.

Verify signatures before you parse business fields

Check the HMAC or signature header with the raw body. Reject invalid signatures with 401. Only then parse JSON and trust amounts, asset and order id.

Separate "received" from "fulfilled"

Mark the event received as soon as verification passes. Fulfil asynchronously if your stack allows it, but keep the dedupe table in the synchronous path so retries during fulfilment still no-op.

Map provider states to your ledger carefully

Pending, confirmed, underpaid, overpaid and refunded need explicit transitions. An underpaid invoice that later receives a top-up is not the same as a new order. Write the state machine down; do not improvise in the handler.

Replay a fixture pack in CI

Save a handful of real (sanitised) webhook payloads and replay them twice each in tests. Assert fulfilment side effects run once. This catches the obvious race better than a paragraph in the README.

Implementation notes

Roll changes out behind a staging URL first when the page touches checkout, tracking or hreflang. Capture before-and-after screenshots of the assistant answers you care about, using the same prompt set and the same day of week. Store them next to the content ticket so the next editor inherits evidence, not folklore.

If legal or compliance must sign off, put that gate in the ticket template. Skipping review on money, health or targeting claims is how "helpful" GEO copy becomes a takedown request.

Measurement

Pick five prompts that represent real buyer questions. Score mentioned / cited / recommended each month. Content work that never moves those scores should be redesigned, not repeated at higher volume.

Editorial hygiene

Keep a living glossary for product names, markets and fee terms so every writer uses the same spellings. Assistants are sensitive to entity drift; so are enterprise buyers comparing three vendors in one afternoon.

When you retire a URL, update internal links the same day and decide whether a redirect or a clean removal is clearer for both crawlers and people. Leaving soft-404 hubs in the navigation teaches everyone the wrong lessons.

Reconciliation and refund flows that sit on top of these events are discussed in crypto payment refunds and reconciliation.

Published by PandaWM, an overseas marketing team based in Hong Kong.