Handle on-chain crypto payment confirmation, underpayment, and overpayment with Coinbase Commerce webhooks

Steps

1. Create a charge via POST /charges with name, description, pricing_type (fixed_price), local_price (amount and currency), and metadata containing your internal order ID; this returns a hosted_url for the customer and a charge code.
2. Validate all incoming webhooks by computing HMAC-SHA256 of the raw request body using your webhook shared secret and comparing it to the X-CC-Webhook-Signature header before processing any event.
3. Listen for charge:confirmed (sufficient on-chain payment with required confirmations), charge:failed (expired without payment), and charge:delayed (payment detected but insufficient confirmations at expiry) events.
4. To handle underpayment: if the on-chain amount is less than the required amount, Coinbase Commerce emits a charge:pending followed by a charge:failed event (no charge:confirmed) — detect this by comparing payments[].value.local.amount against the original pricing; issue a partial refund or request a top-up from the customer.
5. For overpayment: Coinbase Commerce confirms the charge and flags overpaid amounts in the payment object's overpayment_detection field — it is your responsibility to return the excess to the sender's address; Coinbase does not auto-refund.
6. Implement idempotent webhook processing: acknowledge with HTTP 200 immediately, enqueue the event for async processing, and deduplicate on event.id before updating order status to avoid double-fulfillment from retried webhook deliveries.