mirror of
https://github.com/juspay/hyperswitch.git
synced 2025-10-27 19:46:48 +08:00
c8943eb289
Co-authored-by: hyperswitch-bot[bot] <148525504+hyperswitch-bot[bot]@users.noreply.github.com>
46 lines
2.7 KiB
Plaintext
46 lines
2.7 KiB
Plaintext
# Webhooks
|
||
|
||
Webhooks are HTTP-based real-time push notifications that Hyperswitch would use for instant status communication to your server. Webhooks are vital in payments for the following reasons:
|
||
|
||
- Preventing merchants from losing business due to delayed status communication (say, in case of flight or movie reservations where there is a need for instant payment confirmation).
|
||
- Prevent payment reconciliation issues where payments change from “Failed” to “Succeeded”.
|
||
- Providing the best payment experience for the end-user by instantly communicating payment status and fulfilling the purchase.
|
||
|
||
## Configuring Webhooks
|
||
<Steps>
|
||
<Step title="Create an endpoint on your server">You would need to set up a dedicated HTTPS or HTTP endpoint on your server with a URL as a webhook listener that will receive push notifications in the form of a POST request with JSON payload from the Hyperswitch server</Step>
|
||
<Step title="Update your webhook endpoint on Hyperswitch Dashboard"> Update the above endpoint on your Hyperswitch dashboard under Settings -> Webhooks</Step>
|
||
<Step title= "Update Hyperswitch’s webhook endpoints on your connector Dashboard">In order for Hyperswitch to receive updates from the connectors you have selected, you would need to update Hyperswitch’s corresponding endpoints on your respective connector dashboard instead of your webhook endpoints</Step>
|
||
</Steps>
|
||
|
||
Hyperswitch’s webhook endpoint format is as follows:
|
||
|
||
| Environment | Webhook Endpoint |
|
||
| ----------- | ---------------- |
|
||
| Sandbox | sandbox.hyperswitch.io/webhooks/`{merchant_id}`/`{connector_name}` |
|
||
| Production | api.hyperswitch.io/webhooks/`{merchant_id}`/`{connector_name}`|
|
||
|
||
## Handling Webhooks
|
||
|
||
- **Select the events for Webhooks:** On the same page on the dashboard, select the events for which you would like to receive notifications. Currently, Webhooks are available on Hyperswitch for the following events:
|
||
|
||
1. payment_succeeded
|
||
2. payment_failed
|
||
3. payment_processing
|
||
4. action_required
|
||
5. refund_succeeded
|
||
6. refund_failed
|
||
7. dispute_opened
|
||
8. dispute_expired
|
||
9. dispute_accepted
|
||
10. dispute_cancelled
|
||
11. dispute_challenged
|
||
12. dispute_won
|
||
13. dispute_lost
|
||
|
||
<Info>Click [**here**](https://juspay-78.mintlify.app/api-reference/schemas/outgoing--webhook) to see the webhook payload your endpoint would need to parse for each of the above events</Info>
|
||
|
||
- **Return a 2xx response:** Your server must return a successful 2xx response on successful receipt of webhooks.
|
||
|
||
- **Retries:** In case of 3xx, 4xx, or 5xx response or no response from your endpoint for webhooks, Hyperswitch has a retry mechanism that tries sending the webhooks again up to 3 times before marking the event as failed.
|