Webhooks
You can receive webhook events from Ivy. These will notify you once a certain event has happened via a POST Request to your webhook endpoint.
Overview
You can receive webhook events from Ivy. These will notify you once a particular event has happened via a POST Request to your webhook endpoint. You can use these events to update your internal state or trigger other actions. We send notifications for every status change.
You can create new Webhook Subscriptions via the Ivy API or in the Dashboard to receive specific events for your integration or to set a new webhook endpoint.
Webhook validation
Webhooks needs to be validated. We sign them with your webhook signing secret. Please check the implementation details here
Events
The following events are currently supported:
| Event | Description |
|---|---|
merchant_updated | Your merchant account has been updated. |
merchant_app_updated | Your merchant app has been updated. |
order_created | An order has been created. Use this to track the status of a payment. |
order_updated | An order has been updated. Use this to track the status of a payment. |
checkout_session_created | A Checkout Session has been created. |
checkout_session_updated | The Checkout Session has been updated in one of its fields. |
checkout_session_expired | The Checkout Session expired, i.e. the status changed to the final state closed: the Checkout Session is not accessible anymore now. |
checkout_session_completed | The Checkout Session was completed by the user finishing the payment. A corresponding Order exists now. The status changed to final state closed: the Checkout Session is not accessible anymore. |
mandate_setup_succeeded | A mandate has been successfully setup as an outcome of a mandate setup request |
mandate_setup_failed | A mandate could not be setup as an outcome of a mandate setup request |
mandate_revoked | A formerly active mandate has been revoked and can't be used anymore for making charges |
payout_report_requested | Only relevant when creating a payout report. The result of the payout report is sent once the report is fetching is finished. |
data_session_completed | Only relevant for the result of a single data session. The result of the completed data session is sent once the user completes the data session. |
refund_succeeded | DEPRECATED A refund initiated with /merchant/payment/refund succeeded. |
refund_failed | DEPRECATED A refund initiated with /merchant/payment/refund failed. |
Webhook Subscription
You can create a new Webhook subscription via the Ivy API. This will create a new webhook endpoint and subscribe to your specific events. You can also update the webhook endpoint of an existing subscription. The endpoint will be called with a POST request, and the event as JSON body.
Create a new Webhook Subscription
Call the endpoint Create a Webhook Subscription with the following parameters to create a new webhook subscription:
| Parameter | Type | Description |
|---|---|---|
url | string | The URL of your webhook endpoint |
events | array | An array of events you want to subscribe to. See the list of events above. |
Update a Webhook Subscription
Call the endpoint Update a WebhookSubscription with the following parameters to update an existing webhook subscription:
| Parameter | Type | Description |
|---|---|---|
id | string | The id of the webhook subscription |
url | string | The URL of your webhook endpoint |
events | array | An array of events you want to subscribe to. See the list of events above. |
Delete a Webhook Subscription
Call the endpoint Delete a WebhookSubscription with the following parameters to delete an existing webhook subscription:
| Parameter | Type | Description |
|---|---|---|
id | string | The id of the webhook subscription |
Handle a Webhook
Webhook Data Structure
A webhook payload is always structured as follows:
{
"id": "string", // The id of the specific webhook. Use this in the /webhook/trigger endpoint to re-send the webhook.
"type": "string", // The event type of the webhook, see above
"payload": {...}, // The payload to the corresponding event type
"date": "date" // The datetime timestamp of the webhook
}
Reference
For the specific payload for each event, please see the section Webhook-Event
Retry Mechanism
We see the webhook as successfully delivered, only if you respond with HTTP Status 200. If you dont respond with this, we will try to deliver the webhook again in increasing time intervals:
- 1st webhook retry sent 30s after initial failure
- 2nd webhook retry sent 22s after 1st
- 3rd webhook retry sent 140s after 2nd
- 4th webhook retry sent 541s after 3rd
- 5th webhook retry sent 1426s after 4th
- 6th webhook retry sent 3200s after 5th
- …
- 15th webhook retry sent ~54h after 14th
After 15 webhook unsuccessful retries, we will stop trying to send the webhook and instead notify you via email.
Allow List IP Addresses
In case your server blocks incoming requests from unknown IP Adresses by default, there is usually an option to allow-list additional IP addresses. Allow the following IPs to make sure Ivy can send you webhooks successfully:
18.159.27.193
3.120.50.145
3.66.64.118
Receive Webhooks locally
It can get tricky to develop webhooks locally, as your localhost is usually not exposed to the WWW. There are a couple of CLI tools which simplify this for you immensely. We recommend that you use ngrok for this, see here for a well written article on how use ngrok to set up webhooks locally.
Updated 4 months ago