YS Desk uses inbound webhooks to receive billing and subscription events from supported payment providers. The current webhook integration supports Razorpay and PayPal.
Webhook requests are received by dedicated billing endpoints, cryptographically verified, checked for duplicate delivery, processed against the applicable billing state, and acknowledged with HTTP 200 OK when accepted.
YS Desk does not currently expose outbound webhooks for Conversations, Messages, Agents, or other workspace events. Real-time application events are delivered through the Socket.IO Real-Time Gateway instead.
[Real-Time → Overview]
[REST API → API Reference → Billing]
[Guides → Billing & Subscriptions]
Figure WH-01 — Inbound provider webhook ingestion pipeline.
Webhook Architecture
The webhook flow is provider-driven:
Each provider has a dedicated endpoint:
POST /billing/webhooks/razorpay
POST /billing/webhooks/paypal
These endpoints are server-to-server webhook receivers. They are different from the browser return endpoints used after checkout:
/billing/razorpay/return
/billing/paypal/return
The return endpoints handle browser redirection after checkout, while the webhook endpoints process asynchronous provider notifications.
Webhook Processing Model
Every accepted webhook follows the same high-level lifecycle:
- The payment provider sends an HTTP webhook request.
- YS Desk validates the provider-specific signature.
- The event identifier is checked for previous processing.
- New events are passed to the appropriate provider event handler.
- Billing or subscription state is updated when required.
- The webhook is acknowledged with HTTP 200 OK.
Duplicate deliveries are accepted without repeating the associated state mutations.
Supported Providers
| Provider | Webhook Endpoint | Verification |
| Razorpay | POST /billing/webhooks/razorpay | HMAC-SHA256 |
| PayPal | POST /billing/webhooks/paypal | PayPal webhook-signature verification API |
YS Desk currently acts as a Webhook Consumer for these provider integrations.
What YS Desk Webhooks Are Not
YS Desk webhooks should not be confused with the platform’s real-time event system.
Webhook processing is used for external billing-provider events such as subscription activation, payment completion, payment failure, cancellation, and refunds.
Real-time application events such as:
message:new
conversation:updated
user:presence
are handled through Socket.IO and belong to the Real-Time documentation.
Public Webhook Endpoints
Razorpay
POST /billing/webhooks/razorpay
PayPal
POST /billing/webhooks/paypal
No /api prefix should be added to these documented routes.
[Webhooks → Provider Webhooks → Razorpay]
[Webhooks → Provider Webhooks → PayPal]
Webhook Responses
A successfully accepted webhook returns:
{
“received”: true
}
HTTP status:
200 OK
Signature validation failures are rejected with an HTTP 400 Bad Request.
Security Boundary
Webhook secrets authenticate the provider-to-YS-Desk integration. They must never be included in source control, screenshots, logs, or public documentation.
Public examples should use placeholders:
<RAZORPAY_WEBHOOK_SECRET>
<PAYPAL_WEBHOOK_ID>
Do not publish the actual values.
Need Help?
Email: support@ysdesk.com
Documentation: https://docs.ysplugins.com/ys-desk