Introduction

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.

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:

url · string · required

Your webhook endpoint URL where notifications will be sent

events · array · required

Array of event names you want to subscribe to

Update an Existing Subscription

To modify an existing subscription, use the Update a WebhookSubscription endpoint:

id · string · required

The Webhook Subscription ID to update

url · string

New webhook endpoint URL

events · array

Updated array of events to subscribe to

Delete a Subscription

To remove a subscription, use the Delete a WebhookSubscription endpoint:

id · string · required

The Webhook Subscription ID to delete

Handling Webhooks

Webhook Data Structure

Each webhook notification contains the following data:

Webhook Payload Structure

{
  "id": "string",    // Unique webhook ID for resending via /api/service/webhook/trigger
  "type": "string",  // Event type identifier
  "payload": {},     // Event-specific data object
  "date": "date"     // Webhook timestamp
}

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:

1. Initial Retries

   • 30 seconds after initial failure
   • 22 seconds after 1st retry
2. Mid-Range Retries

   • 140 seconds after 2nd retry
   • 541 seconds after 3rd retry
   • 1,426 seconds after 4th retry
3. 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:

Production

18.159.27.193
3.120.50.145
18.158.26.25
18.158.95.0
3.122.16.89

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.

Webhook Logs in the Dashboard

The Ivy Dashboard provides a comprehensive Webhook Logs view to help you monitor, debug, and manage webhook deliveries in real time.

Webhook Logs overview in the Ivy Dashboard

Key features:

• See a paginated history of all webhook deliveries for each subscription
• View delivery status (Delivered, Failed, etc.) at a glance
• Inspect event type and timestamp for each webhook
• Click any log entry to see full request and response payloads
• Manually resend individual webhook events for troubleshooting
• Filter or search by event type, status, or date
• Bulk history navigation for large volumes of events

Use the Dashboard’s Webhook Logs to quickly identify delivery issues, verify event payloads, and ensure your integration is working as expected.