Configure Webhooks

Configuring webhooks involves setting up an endpoint to receive real-time notifications from Zoho Payments for specific events. Follow the steps below to configure your webhook:

Create a Webhook Endpoint
Secure the Webhook Endpoint
Register the Webhook Endpoint
Testing Webhooks
Retry Mechanism

Prerequisites: Ensure that you have allowed or whitelisted the API domains of Zoho Payments to accept the webhooks sent.

1. Create a Webhook Endpoint

Set up an HTTPS URL endpoint that accepts POST requests from Zoho Payments. Ensure that you have allowed or whitelisted the API domains of Zoho Payments to accept the webhooks sent.

Once the webhook is received, this endpoint should respond with a 200 OK HTTP status code.

2. Secure the Webhook Endpoint

You can secure the endpoint by validating and verifying that the requests received are from Zoho Payments.

Zoho Payments provides a signature in the webhook’s header, which should be extracted and verified using the webhook signing key. This key will be provided when you register the webhook endpoint in the next step.

Note: Do not consume the webhook data without verifying the signature of the request.

Additionally, you can whitelist and check the IPs from which the webhooks will be triggered. If the IPs do not match, decline the webhook.

3. Register the Webhook Endpoint in Zoho Payments

To register the webhook endpoint:

Go to Settings and select Developer Space.
Switch to Webhooks.
Add your webhook endpoint here and choose the events for which you want to receive webhooks. You can configure a single endpoint for multiple events or different endpoints for each event.

Zoho Payments checks the endpoint during registration by pinging the URL once. Ensure that you have the endpoint set up and publicly accessible before registering it in Zoho Payments. If the endpoint is not accessible, the registration will fail.

Insight: You can register up to 5 endpoints in your account.

4. Testing Webhooks

Once registered, you can perform any actions that will trigger the subscribed events to your endpoint. You can check the status of webhook delivery and view logs in Zoho Payments > Settings >Developer Space > Webhooks.

Insight: Zoho Payments retries webhooks for up to 2 days with exponential backoff. If the webhook still fails to be delivered, Zoho Payments will notify you via email and disable the endpoint.

Retry Mechanism

Retry mechanism ensures that failed webhook notifications are retried automatically to minimise missed events.

Zoho Payments will attempt to retry failed webhooks every hour on the first day and every two hours on the second day. If the webhook continues to fail and does not receive a successful 200 HTTP status code response, we will disable the webhook and notify you via email.

Once the issue with the endpoint is resolved, you can re-enable the webhook.