Webhooks
Receive event notifications from Ivy through POST requests to your webhook endpoint.
Overview
Ivy’s Webhook system allows you to receive event notifications whenever specific actions occur in your integration. These notifications are sent as POST requests to your designated webhook endpoint.
Key Uses
- Update your internal system state
- Trigger follow-up actions
- Track status changes in real-time
You can create new Webhook Subscriptions through either the Ivy API or Dashboard to:
- Receive specific events for your integration
- Configure new webhook endpoints
All Webhooks must be validated. Ivy signs them with your Webhook Signing Secret. Please review the implementation details in our Authentication documentation.
Supported Events
Managing Webhook Subscriptions
The Ivy API provides several endpoints to manage your webhook subscriptions. Here are the key operations:
Create a New Subscription
To create a new subscription, use the Create a Webhook Subscription endpoint:
Your webhook endpoint URL where notifications will be sent
Array of event names you want to subscribe to
Update an Existing Subscription
To modify an existing subscription, use the Update a WebhookSubscription endpoint:
The Webhook Subscription ID to update
New webhook endpoint URL
Updated array of events to subscribe to
Delete a Subscription
To remove a subscription, use the Delete a WebhookSubscription endpoint:
The Webhook Subscription ID to delete
Handling Webhooks
Webhook Data Structure
Each webhook notification contains the following data:
For detailed information about event-specific payloads, see the Webhook Events documentation.
Retry Mechanism
A webhook delivery is only considered successful when your endpoint responds with HTTP Status 200.
For failed deliveries, Ivy implements an exponential backoff retry schedule:
Initial Retries
- 30 seconds after initial failure
- 22 seconds after 1st retry
Mid-Range Retries
- 140 seconds after 2nd retry
- 541 seconds after 3rd retry
- 1,426 seconds after 4th retry
Extended Retries
- 3,200 seconds after 5th retry
- Continues up to the 15th retry (~54 hours after 14th)
After 15 unsuccessful retries, Ivy stops delivery attempts and sends you an email notification.
Allow List IP Addresses
If your server implements IP filtering, add these Ivy webhook IPs to your allowlist:
Local Development Testing
Since localhost isn’t accessible from the internet, we recommend using ngrok for local webhook testing.
For detailed guidance on setting up ngrok for webhook development, see this guide.