Appearance
Webhooks and Payment Links
Most payments in this gateway are confirmed instantly through the widget checkout. But some payments arrive asynchronously — most importantly Payment Links, where the customer pays outside the live invoice session. For those, Zoho notifies your WHMCS install through a signed webhook.
This page explains what the webhook is for, how to set it up, and how it keeps your invoices in sync safely.
What is a webhook?
A webhook is a message Zoho sends to your server when something happens — here, when a payment completes. It lets WHMCS learn about a payment even when the customer isn't on the invoice page.
Why you need it
- Payment Links let you collect a payment without the customer sitting on the WHMCS invoice. When they pay, there's no browser session to update the invoice — the webhook does it instead.
- It's your safety net for the Payment completed event too, so a payment is recorded even if something interrupts the on-page flow.
Setting up the webhook
In your Zoho Payments dashboard, add a webhook pointing at your WHMCS install:
- Webhook URL:
https://yourdomain.com/modules/gateways/zohopayments/webhooks/paylink_webhook.php - Events: Payment completed and Payment Link paid
- Secret: copy the webhook secret Zoho gives you into the Webhook Secret field under Setup → Payment Gateways → Zoho Payments
Find your URL in the config
The Webhook Secret field in the gateway settings also displays your exact Webhook URL — copy it straight from there to avoid typos.
Setup → Payment Gateways → Zoho Payments (Webhook Secret / Webhook URL)
How a Payment Link gets recorded
When a customer pays through a Payment Link, the flow is:
| Step | What happens |
|---|---|
| Customer pays | The customer completes the payment via the Zoho Payment Link |
| Zoho notifies | Zoho sends a signed webhook to your Webhook URL |
| Signature checked | WHMCS verifies the message with HMAC-SHA256 using your Webhook Secret |
| API re-verified | WHMCS also confirms the payment against the Zoho API |
| Invoice updated | The matching invoice is marked Paid, with details and fees recorded |
The double check — signature and API verification — means a forged or replayed webhook can't mark an invoice paid. See Security for more.
The webhook needs SSL
Zoho only sends webhooks to a valid HTTPS endpoint. Make sure your Webhook URL is reachable over SSL and the Webhook Secret matches exactly, or Payment Link payments won't be recorded.
When something's wrong
If a Payment Link payment doesn't appear as Paid, check the Gateway Log first (Utilities → Logs → Gateway Log). Confirm the Webhook URL is reachable, the Webhook Secret matches, and your SSL certificate is valid. The troubleshooting page covers the common causes.