Webhook Payment Notifications: Real-Time Order Confirmation with Crypto

Blockchain transactions are asynchronous by nature — a customer pays, and confirmation arrives minutes later. Webhooks bridge that gap, delivering real-time payment events directly to your server so orders are fulfilled the instant funds are confirmed.

When a customer pays with crypto at checkout, the transaction enters a mempool, gets included in a block, and eventually reaches sufficient confirmations for finality. This process can take anywhere from 400 milliseconds on Solana to 60 minutes on Bitcoin. Without a reliable notification system, your application has no way of knowing when to ship the product, activate the subscription, or update the order status. Polling the blockchain or the payment API on a loop is wasteful, unreliable, and introduces unnecessary latency. 94% of production crypto payment integrations solve this with webhooks — HTTP callbacks that push payment events to your server the moment they occur. The median delivery time is just 1.2 seconds.

What Webhooks Are and Why They Matter

A webhook is an HTTP POST request that a payment processor sends to a URL you configure whenever a specific event occurs. Rather than your server asking “has the payment been confirmed yet?” every few seconds, the payment processor tells your server the moment something changes. This inversion of control — push instead of pull — is what makes real-time order fulfilment possible.

In traditional payment processing with Stripe or PayPal, webhooks are already standard practice. The difference with crypto payments is that the underlying confirmation mechanism is a public blockchain rather than a private banking network. This introduces unique timing characteristics: a credit card authorisation resolves in 1–3 seconds, while a Bitcoin payment might need six confirmations over 60 minutes. Webhooks abstract this complexity, delivering a normalised event to your server regardless of which chain the customer paid on.

Payment Event Types

A well-designed webhook system emits distinct events for each stage of the payment lifecycle. Understanding these events is critical for building correct order management logic. Most crypto payment processors, including SpacePay, support the following event types.

The distinction between payment.confirmed and payment.completed is important. Confirmation means the transaction has enough block confirmations to be considered irreversible with high probability. Completion means the payment processor has finished settlement — including any fiat conversion or fiat off-ramping — and funds are available in your merchant account. For most digital goods and services, you can safely fulfil on payment.confirmed. For high-value physical goods, waiting for payment.completed adds an additional safety margin.

Webhook Payload Structure

Every webhook delivery contains a JSON payload with all the information your server needs to process the event. A well-structured payload eliminates the need for follow-up API calls and enables fully self-contained event processing. A typical payload includes the following fields.

• event_type — The event name, such as payment.confirmed.
• event_id — A unique identifier for this specific event, used for idempotency and deduplication.
• timestamp — ISO 8601 timestamp of when the event was generated.
• payment_id — The unique identifier of the payment session or invoice.
• amount — The payment amount in the original currency, along with the crypto amount and exchange rate used.
• chain — The blockchain network the payment was made on (e.g., ethereum, solana, polygon).
• tx_hash — The on-chain transaction hash, allowing you to independently verify the payment on a block explorer.
• confirmations — The number of block confirmations at the time the event was emitted.
• metadata — Any custom key-value pairs you attached when creating the payment, such as your internal order ID or customer reference.

The metadata field is particularly valuable for reconciliation. By passing your internal order ID when creating the payment, it comes back in every webhook, eliminating the need to maintain a separate mapping between payment IDs and order IDs.

Securing Webhook Endpoints

An unsecured webhook endpoint is a critical vulnerability. If an attacker can send forged webhook payloads to your server, they can trigger order fulfilment without ever paying. Three layers of security work together to prevent this.

HMAC Signature Verification

Every webhook request includes a signature header computed using HMAC-SHA256 over the raw request body, keyed with a secret that only you and the payment processor share. Your server must recompute the HMAC using the same secret and compare it to the header value. If they do not match, the request must be rejected immediately. This is the single most important security measure — it cryptographically proves the webhook originated from the payment processor and has not been tampered with in transit. Always compare signatures using constant-time comparison functions to prevent timing attacks.

IP Whitelisting

As an additional layer, restrict your webhook endpoint to only accept requests from the payment processor's published IP ranges. This prevents attackers from even reaching your signature verification logic. Most payment processors publish a static list of IP addresses used for webhook delivery, and cloud providers like AWS, GCP, and Cloudflare make it straightforward to configure IP-based access controls at the load balancer or firewall level.

Replay Attack Prevention

Even with valid signatures, a captured webhook could be replayed by an attacker who intercepts the request. To prevent this, the timestamp included in the signed payload should be validated against a tolerance window — typically five minutes. If the timestamp is older than the window, reject the request. Additionally, store processed event IDs and reject any duplicates. This combination of timestamp validation and idempotency key tracking ensures each event is processed exactly once.

Implementation Patterns

A production-grade webhook handler follows a specific pattern that maximises reliability and minimises the risk of missed events.

• Acknowledge immediately. Return a 200 OK response as fast as possible after validating the signature. Do not perform business logic synchronously in the request handler. If your endpoint takes longer than 10–30 seconds to respond, most processors will treat it as a failure and retry.
• Enqueue for async processing. Push the validated event onto a message queue (SQS, RabbitMQ, Redis Streams, or a database-backed job queue). A separate worker processes the event, updates order status, triggers fulfilment, and sends email notifications.
• Idempotent processing. Because webhooks can be retried, your processing logic must be idempotent. Use the event_id as a deduplication key. Before processing, check whether the event has already been handled. If so, skip it.
• Ordered processing per payment. Events for the same payment should be processed in order. A payment.completed event arriving before payment.confirmed has been processed can cause inconsistent state. Use the payment_id as a partition key in your queue to ensure sequential processing per payment.
• Dead letter queue. Events that fail processing after multiple retries should be routed to a dead letter queue for manual investigation rather than silently dropped.

Retry Logic and Failure Handling

Network failures, server downtime, and temporary errors are inevitable. A robust webhook system handles these gracefully through automatic retries with exponential backoff. If your server returns a non-2xx status code or the connection times out, the payment processor queues the webhook for redelivery. A typical retry schedule follows exponential backoff: 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours, and 24 hours. After all retries are exhausted, the webhook is marked as failed and an alert is generated.

SpacePay retains all webhook events for 30 days and provides a dashboard where you can inspect delivery attempts, view response codes, and manually replay any failed webhook. This is invaluable during incident recovery — if your server was down for an hour, you can replay all missed events in sequence once it is restored.

Common Pitfalls to Avoid

After working with thousands of merchant integrations, certain mistakes appear repeatedly. Avoiding these from the start saves significant debugging time.

• Processing webhooks synchronously. Heavy database operations, external API calls, or email sending in the request handler causes timeouts and duplicate deliveries. Always acknowledge first, process later.
• Skipping signature verification. Even in development environments, always verify signatures. Skipping verification in staging and forgetting to enable it in production is a common path to fraud.
• Ignoring event ordering. Webhooks can arrive out of order due to network conditions and retry timing. Your logic must handle a payment.completed arriving before a payment.confirmed without creating duplicate fulfilments.
• Hardcoding the webhook secret. Store your webhook signing secret in environment variables or a secrets manager, never in source code. Rotate secrets periodically and support multiple active secrets during the rotation window.
• No monitoring or alerting. If webhook deliveries start failing, you need to know immediately. Monitor your endpoint's response rate and set up alerts for elevated error rates or increased latency.

Webhooks vs. Polling: A Direct Comparison

Frequently Asked Questions

What is a webhook in the context of crypto payments?

A webhook is an HTTP callback that a payment processor sends to your server when a specific event occurs, such as a payment being confirmed on the blockchain. Instead of your server repeatedly polling for updates, the payment processor pushes notifications to a URL you configure, enabling real-time order fulfilment without wasted API calls.

How fast are webhook payment notifications delivered?

The median delivery time across modern crypto payment processors is approximately 1.2 seconds from the moment the event is detected on-chain. This includes payload construction, HMAC signing, and HTTP delivery. Actual end-to-end latency also depends on blockchain confirmation times for the underlying network.

How do I verify that a webhook is authentic?

Verify the HMAC-SHA256 signature included in the request headers by recomputing it using your shared secret and comparing it to the provided value. Always use constant-time comparison to prevent timing attacks. Layer on IP whitelisting and timestamp validation for defence in depth.

What happens if my server is down when a webhook is sent?

Reliable processors implement automatic retry logic with exponential backoff, typically retrying over 24 to 72 hours. SpacePay retains all events for 30 days and provides a dashboard for manual replay, ensuring no payment events are permanently lost during outages.

Should I process webhooks synchronously or asynchronously?

Always asynchronously. Return a 200 OK immediately after signature verification, then enqueue the event for background processing. This prevents timeouts, reduces unnecessary retries, and decouples your webhook endpoint from downstream service failures.

Can I test webhooks in a development environment?

Yes. SpacePay's sandbox environment sends real webhook events to your configured endpoint when test payments are made on testnets. You can also use tools like ngrok to expose a local development server to receive webhooks, and the dashboard allows you to replay events at will for debugging.

What is replay attack prevention for webhooks?

Replay prevention ensures a captured webhook cannot be re-sent by an attacker. It works by validating the timestamp in the signed payload against a tolerance window (typically five minutes) and tracking processed event IDs to reject duplicates. Combined, these mechanisms guarantee each event is processed exactly once.

Conclusion

Webhooks are the backbone of any production crypto payment integration. They transform the inherently asynchronous nature of blockchain transactions into real-time, actionable events that drive order fulfilment, inventory management, and customer communication. With HMAC signature verification, IP whitelisting, replay prevention, and idempotent async processing, your webhook handler becomes both reliable and secure. The 94% adoption rate is not a coincidence — it reflects the fact that webhooks are the only practical way to build responsive, scalable crypto commerce.