An online store needs to know when a customer has paid so it can update the order and begin fulfilment. The payment provider has that information, but the store’s application needs a way to receive it. A webhook sends the update directly to the application’s server.

The same approach can support other workflows, such as updating a refund record or notifying the finance team about a failed payout. Developers choose which events the application receives and what should happen after each notification.

Payment webhooks: How they work and what to consider when integrating them

What is a payment webhook?

A payment webhook is an HTTP notification sent by a payment provider when a subscribed event occurs. It is delivered to an endpoint, a URL on your server set up to receive the request.

The request contains a payload, usually JSON data identifying the event and the payment or other record involved. Your application verifies the request, finds the corresponding order or record, and performs the appropriate update.

Webhooks reduce the need for polling, where your server repeatedly calls an API to check for changes. API requests remain useful for retrieving current status, investigating a discrepancy, or recovering an update that did not reach your application.

How an event reaches your application

Consider a successful payment for an online order:

1. The payment succeeds. The provider creates an event containing the payment details.

2. The provider sends a notification. An HTTP POST request delivers the event to your registered endpoint.

3. Your server verifies and accepts it. The endpoint checks the signature, saves the event for processing, and acknowledges receipt.

4. Your application updates the order. It matches the payment to the order, checks the amount and currency, and records the payment before triggering fulfilment or a receipt.

This server-to-server update can reach your application even if the customer closes the checkout page. A browser callback can still help display the result, while the webhook supports the application’s payment records.

Choosing events for your workflow

Start with the actions your application needs to perform. Order management needs payment updates; refund handling needs refund updates; finance reporting may also need payout notifications.

For example, these Zoho Payments events support different workflows:

A payment event concerns the customer’s transaction. A payout event concerns funds being paid out to the business. Use payment status to drive order handling; follow payouts separately as part of reconciliation. Our articles on card payment processing and payouts explain these stages in more detail.

Preparing your webhook endpoint

Set up a publicly accessible HTTPS URL that accepts POST requests. Register it with your provider, select the events you need, and securely store the signing key supplied for verifying deliveries.

Your handler needs to recognize each subscribed event, identify the affected record, and decide which update to make. Keep the endpoint’s initial work short: verify the request and save it reliably, then return the required success response. A queue lets slower tasks, such as sending emails, run afterward.

Verify requests before processing them

A webhook signature lets your server check the request’s authenticity and integrity using a shared secret key. HMAC is one mechanism used for this verification.

With Zoho Payments, the X-Zoho-Webhook-Signature header contains a timestamp (t) and signature (v). Verification combines the timestamp, a dot, and the complete request payload, then calculates HMAC-SHA256 using the webhook’s signing key. Compare the result with v before accepting the event.

Preserve the payload as received for verification; parsing and rebuilding the JSON can change the signed content. Keep the signing key on your server and reject requests that fail verification.

Prevent repeated deliveries from repeating actions

Your endpoint may receive an event more than once. Store its event ID and make processing idempotent, so another delivery does not send a second receipt or trigger fulfilment again. In Zoho Payments, use event_id to recognize repeated events.

Separate events can also affect the same order. For example, a customer may retry after a failed payment attempt. Before acting on payment.failed, check the payment session using payments_session_id; a later attempt within that session may have succeeded. Apply delayed updates against the current record so an older failure does not overwrite a successful payment.

Handling failed deliveries

If your endpoint times out or returns an error, the provider may retry the notification. With Zoho Payments, failed deliveries are retried for up to two days with increasing intervals between attempts. Continued failure leads to the webhook being disabled and an email notification.

Review delivery logs to identify the cause, fix the endpoint, and re-enable it. Check payment records for the affected period and use API status requests to recover missing updates. Confirm which orders need changes before repeating downstream actions.

The endpoint’s acknowledgement tells the provider that it has accepted the event. Monitor your application’s processing separately so a queued event that fails later is also caught.

Testing and monitoring the integration

Test the application update as well as delivery. A successful HTTP response does not establish that the correct order was updated.

Before launch, check that:

• A valid event updates the correct record, with the expected amount and currency.

• An invalid signature is rejected without changing records.

• Delivering the same event again does not repeat fulfilment or notifications.

• A failed payment attempt followed by a successful retry leaves the order in the correct state.

• A temporary endpoint failure can be diagnosed and missing updates recovered.

Keep delivery and processing logs that connect the event ID, payment ID, and order reference. Alert the responsible team to repeated delivery failures or processing errors so they can investigate affected records.

Using webhooks with Zoho Payments

In Zoho Payments, go to Settings > Developer Space > Webhooks to register an endpoint and select events. You can review delivery logs and manage signing keys from the same area.

For configuration, verification, and supported events, follow the integration steps for India or the US. Start with the events your application needs, then test the complete flow from notification to record update.