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.

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.

Events

The following events are currently supported:

EventDescription
merchant_updatedYour merchant account has been updated.
merchant_app_updatedYour merchant app has been updated.
order_createdAn order has been created. Use this to track the status of a payment.
order_updatedAn order has been updated. Use this to track the status of a payment.
refund_succeededA refund initiated with /merchant/payment/refund succeeded.
refund_failedA refund initiated with /merchant/payment/refund failed.
payout_report_requestedOnly relevant when creating a payout report. The result of the payout report is sent once the report is fetching is finished.
data_session_completedOnly 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.

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:

ParameterTypeDescription
urlstringThe URL of your webhook endpoint
eventsarrayAn 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:

ParameterTypeDescription
idstringThe id of the webhook subscription
urlstringThe URL of your webhook endpoint
eventsarrayAn 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:

ParameterTypeDescription
idstringThe id of the webhook subscription

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