curl -X POST 'https://api.getivy.de/api/service/internal/webhook-subscription/create' \
  -H 'Content-Type: application/json' \
  -H 'X-Ivy-Api-Key: YOUR_API_KEY' \
  -d '{
    "endpoint_url": "https://your-domain.com/webhooks/ivy",
    "event_types": [
      "checkout_session.completed",
      "payout.paid",
      "refund.succeeded"
    ],
    "description": "Production webhook for payment notifications"
  }'

{
  "id": "wsub_1234567890",
  "endpoint_url": "https://your-domain.com/webhooks/ivy",
  "event_types": [
    "checkout_session.completed",
    "payout.paid",
    "refund.succeeded"
  ],
  "status": "active",
  "description": "Production webhook for payment notifications",
  "created_at": "2024-01-15T10:30:00Z",
  "webhook_signing_secret": "whsec_abc123def456..."
}

​
Overview

Create a new webhook subscription to receive real-time notifications when specific events occur in your Ivy account. Webhooks allow you to stay informed about payment status changes, checkout completions, and other important events without polling the API.
This endpoint requires authentication using your API key in the X-Ivy-Api-Key header.

​
Request Parameters

​
endpoint_url
string
required
The URL where webhook events will be sent. Must be a valid HTTPS URL.
​
event_types
array
required
Array of event types to subscribe to. Available event types include:
  • checkout_session.completed - When a checkout session is successfully completed
  • checkout_session.expired - When a checkout session expires
  • payout.paid - When a payout is successfully processed
  • payout.failed - When a payout fails
  • refund.succeeded - When a refund is successfully processed
  • refund.failed - When a refund fails
​
description
string
Optional description for the webhook subscription to help identify its purpose.

​
Example Request

curl -X POST 'https://api.getivy.de/api/service/internal/webhook-subscription/create' \
  -H 'Content-Type: application/json' \
  -H 'X-Ivy-Api-Key: YOUR_API_KEY' \
  -d '{
    "endpoint_url": "https://your-domain.com/webhooks/ivy",
    "event_types": [
      "checkout_session.completed",
      "payout.paid",
      "refund.succeeded"
    ],
    "description": "Production webhook for payment notifications"
  }'

​
Example Response

{
  "id": "wsub_1234567890",
  "endpoint_url": "https://your-domain.com/webhooks/ivy",
  "event_types": [
    "checkout_session.completed",
    "payout.paid",
    "refund.succeeded"
  ],
  "status": "active",
  "description": "Production webhook for payment notifications",
  "created_at": "2024-01-15T10:30:00Z",
  "webhook_signing_secret": "whsec_abc123def456..."
}

​
Webhook Security

​
Keep your webhook signing secret secure!

The response includes a webhook_signing_secret that you’ll need to verify webhook signatures. Store this securely and never expose it in client-side code.
All webhook requests include an X-Ivy-Signature header that you can verify using the webhook signing secret to ensure the request is coming from Ivy.

​
Error Responses

{
  "error": {
    "code": "invalid_endpoint_url",
    "message": "The provided endpoint URL is invalid. Must be a valid HTTPS URL.",
    "type": "validation_error"
  }
}

{
  "error": {
    "code": "invalid_event_types",
    "message": "One or more event types are not supported",
    "type": "validation_error"
  }
}

​
Next Steps

After creating a webhook subscription:
  1. Test the webhook: Use the trigger test webhook endpoint to verify your endpoint is working
  2. Implement signature verification: Use the webhook signing secret to verify incoming webhook requests
  3. Monitor webhook delivery: Check the list webhook subscriptions endpoint to monitor delivery status