What Is a Payment Webhook? How Crypto Merchants Use Callbacks

A system polling a payment gateway every 30 seconds makes 2,880 API calls per day per merchant, and that is before a single payment happens. Every one of those calls is wasted compute, wasted network, and wasted latency. Webhooks eliminate all of it.

For crypto merchants, the webhook question has an extra layer: delivery reliability. A failed webhook means a missed payment confirmation, so HMAC signatures and retry queues are what separate a production-ready crypto payment integration from one that breaks under real operating conditions.

What a Webhook Is

A webhook (also called a callback) is an HTTP POST request your payment gateway sends to a URL you define, which is your server, when a specific event occurs.

You register a URL such as https://yourstore.com/webhooks/payments with the gateway. When a customer's payment is detected, confirmed, or expires, the gateway fires a POST to that URL with a JSON payload describing the event. Your application reads the event, updates the order state, and triggers the appropriate action, whether that is fulfilling the order, sending a confirmation email, or releasing the download.

The key property is that the gateway contacts you. You do not ask the gateway what happened. It tells you when it happens.

Polling vs Webhooks: Why Webhooks Win

Polling means your application repeatedly asks the gateway "is this payment confirmed yet?" at a fixed interval. Every request returns "no" until it returns "yes." The problems with this approach are structural, and they compound as transaction volume grows.

• Latency: A payment confirmed 5 seconds after your last poll will not be detected for up to 30 seconds, or whatever your interval is. For crypto payments where on-chain confirmation times vary from seconds on Tron to minutes on Ethereum, that latency gap is meaningful.
• API quota waste: Every poll call consumes rate limit. At 30-second intervals, that is 2,880 calls per day per active order window. At 100 concurrent order windows, it is 288,000 calls per day for nothing.
• Infrastructure load: Polling at scale means your server is constantly initiating outbound HTTP connections to the gateway, regardless of whether anything has happened.
• Missed events: If a payment expires between poll cycles, you may miss the expiry event and leave the order in an ambiguous state.

Webhooks eliminate all of these problems. The gateway knows exactly when each event occurs and fires exactly one HTTP call at that moment. As a result, your application only does work when there is something to do.

The Three Webhook Events Every Crypto Merchant Needs

Most crypto payment gateways fire multiple event types. Three are non-negotiable for any production integration.

1. Payment Detected

Funds have appeared on-chain but have not yet reached the required confirmation count. This is a "pending" state, which is useful for showing customers a real-time "payment received, awaiting confirmation" message. Do not fulfill orders based on this event alone. Unconfirmed transactions can be replaced on some chains.

2. Payment Confirmed

The transaction has reached the required number of block confirmations for your configuration. This is the safe-to-fulfill event. Trigger order fulfillment, download delivery, subscription activation, or whatever the business action is. This is the event your order management system should wait for.

3. Payment Expired

The invoice window closed, meaning your configured time limit passed without a confirmed payment meeting the required amount. Once you receive this event, notify the customer, release any reserved inventory, and mark the order as expired in your system. Without handling this event, expired orders accumulate in a "pending" state and create reconciliation noise.

What Can Go Wrong With Unsigned Webhooks

If your webhook endpoint accepts any POST request without verifying the sender, an attacker can fake a payment confirmation. The attack is simple: send a POST to your webhook URL with a JSON payload claiming a large payment was confirmed. If your code processes it, the attacker gets their order fulfilled without paying.

This is not a theoretical edge case. Payment fraud via forged webhooks has been documented across multiple gateway integrations that shipped without signature verification.

The fix is HMAC verification, and it needs to be implemented correctly.

HMAC Verification: How It Works

HMAC (Hash-based Message Authentication Code) is a cryptographic signature mechanism. Here is the flow.

1. You and your gateway share a secret key, set during integration setup.
2. When the gateway fires a webhook, it computes an HMAC of the raw request body using the shared secret and includes the result as a header such as X-AIO-Signature.
3. Your server receives the request. Before processing any fields, it recomputes the HMAC of the raw body using the same shared secret.
4. If your computed signature matches the header value, the payload is authentic. Process it. If not, reject it with a 401 or 400 and log the attempt.

Critical implementation note: always compute the HMAC against the raw bytes of the request body, not a parsed version. JSON parsers can reorder keys or strip whitespace, which changes the hash. Read the raw body first, verify, then parse.

Retry Logic: Why It Matters

Your webhook endpoint will go down at some point. Deployments, maintenance windows, and transient errors all produce non-2xx responses that the gateway interprets as delivery failure.

Without a retry mechanism, a failed delivery silently loses the event. Your order stays in "pending" indefinitely. The payment was confirmed on-chain, but your application never found out.

A well-implemented retry pool queues failed events and retries them on an exponential backoff schedule, for example 1 minute, then 5 minutes, then 30 minutes, then 2 hours. If your endpoint recovers within a few hours, the event still gets delivered. AIO also provides manual resend from the merchant dashboard, which is useful when debugging an integration issue that caused systematic webhook failures.

Secret Rotation

Your HMAC shared secret should be treated like a password, rotated periodically and rotated immediately if it may have been exposed. Some gateways require a downtime window to rotate webhook secrets, while AIO allows secret rotation with a brief overlap window so no events are dropped during the rotation.

Rotate secrets in the following situations.

• After any team member with access to the secret leaves the organisation
• After any suspected security incident affecting your server or environment variables
• On a regular schedule such as quarterly, as a baseline hygiene practice

AIO's Webhook Implementation

AIO implements HMAC-signed callbacks across all payment event types. The retry pool handles failed deliveries automatically. Manual resend is available from the merchant dashboard for specific events, which is useful when you need to replay an event during development or after a targeted outage.

Every payment event carries a trace ID that matches the original payment request, making it straightforward to correlate webhook events with the corresponding order in your system. This matters at scale, because when you have thousands of concurrent payment sessions, a trace ID is what makes reconciliation and debugging tractable rather than a manual grep exercise.

For developers building or auditing their integration, read the detailed guide to HMAC-signed crypto payment webhooks and review the crypto payment security guide for the full security model. If you are starting from scratch, the merchant integration guide covers the full integration flow.

Accept Crypto Payments: Merchant Guide · HMAC-Signed Crypto Payment Webhooks · Crypto Payment Security Guide for Merchants