Webhook Delivery & Idempotency
Payment providers may deliver the same webhook more than once. YS Desk therefore treats webhook handling as an idempotent operation.
The core rule is:
A previously processed provider event must not execute its billing side effects again.
Figure WH-05 — Webhook delivery deduplication and state boundary.
Processing Lifecycle
The public webhook processing flow is:
Idempotency Key
The primary idempotency identifier is the provider’s event identifier.
For both providers, YS Desk normally uses:
The event is associated with the relevant provider so that identifiers from different providers remain independent.
Duplicate Delivery
When a webhook has already been processed:
- YS Desk detects the existing provider/event combination.
- The duplicate event is skipped.
- No duplicate billing mutation is executed.
- The request is acknowledged with HTTP 200 OK.
This allows the provider to retry delivery without causing duplicate subscription or payment operations.
New Event Processing
For a new event:
- The provider signature is verified.
- The event identifier is checked.
- The event is dispatched to the provider-specific handler.
- The applicable subscription, payment, or refund state is processed.
- The event is recorded for duplicate detection.
- YS Desk returns:
200 OK
{
“received”: true
}
Duplicate Event Example
A provider may deliver:
{
“id”: “<WEBHOOK_EVENT_ID>”,
“event”: “subscription.activated”
}
more than once.
The first delivery is processed normally.
A repeated delivery containing the same provider/event identifier is recognized as a duplicate and acknowledged without repeating the original billing side effects.
Failure and Retry Behavior
A provider may retry a webhook when it does not receive the expected successful response.
YS Desk therefore distinguishes between:
Accepted webhook
The event passes verification and is accepted for processing.
HTTP 200
Rejected webhook
The request fails verification or required validation.
Idempotency Boundary
Idempotency applies to the webhook event itself, not to an arbitrary HTTP request.
The effective identity is:
Provider + Provider Event ID
For example:
Razorpay + <WEBHOOK_EVENT_ID>
PayPal + <WEBHOOK_EVENT_ID>
This ensures an event processed by Razorpay does not collide with an unrelated event carrying the same identifier from another provider.
Delivery and Billing State
Webhook processing exists to synchronize YS Desk’s billing state with the payment provider.
Examples include:
Subscription Activated
Subscription Updated
Payment Captured
Payment Failed
Subscription Suspended
Subscription Cancelled
Refund Created
Refund Processed
The webhook event should therefore be treated as an external billing notification rather than as a general application event stream.
Webhook Acknowledgement
For accepted requests, YS Desk returns:
{
“received”: true
}
with:
HTTP 200 OK
Duplicate events are also acknowledged successfully after being recognized as already processed.
This allows provider retries to terminate without producing duplicate state changes.
Monitoring Delivery Failures
The current public webhook contract does not expose a dedicated YS Desk webhook delivery-log interface.
For this reason, the documentation should not instruct developers to monitor webhook deliveries from a YS Desk webhook dashboard.
Provider-side webhook delivery history remains the appropriate place to inspect provider delivery attempts, while YS Desk handles verification, processing, and duplicate-event protection on the receiving side.
Need Help?
Email: support@ysdesk.com
Documentation: https://docs.ysplugins.com/ys-desk