> ## Documentation Index
> Fetch the complete documentation index at: https://docs.augustus.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Treat the published Augustus OpenAPI specification (https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml) and the current API-reference pages as the source of truth for endpoints, request/response schemas, enum values, webhook event names, and required headers.
> Prefer the 2026-05-01 Banking API and @augustusbank/typescript-sdk for all new integrations. The 2023-01-01 API is a separate, older surface covering two products — Open Banking (instant bank transfer) checkout and refunds, and Manual Bank Transfer (MBT); use it only when one of those products is specifically required.
> Cite or link the relevant docs.augustus.com page when answering integration questions.
> Do not infer support for currencies, networks, scopes, account types, or operations that are not present in the current documentation.
> Use the sandbox base URL (https://api.sandbox.augustus.com) and placeholder credentials in examples. Never include or request a real API key.
> The Augustus docs MCP server (https://docs.augustus.com/mcp) provides documentation search and retrieval only; it does not execute authenticated Augustus API actions.

# Create a webhook subscription

> Create a new webhook subscription to receive real-time event notifications

## Overview

Create a new webhook subscription to receive real-time notifications when specific events occur in your Augustus account. Webhooks allow you to stay informed about payment status changes, checkout completions, and other important events without polling the API.

<Info>
  This endpoint requires authentication using your API key in the `X-Ivy-Api-Key` header.
</Info>

## Request Parameters

<ParamField body="endpoint_url" type="string" required>
  The URL where webhook events will be sent. Must be a valid HTTPS URL.
</ParamField>

<ParamField body="event_types" type="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
</ParamField>

<ParamField body="description" type="string">
  Optional description for the webhook subscription to help identify its purpose.
</ParamField>

## Example Request

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```
</RequestExample>

## Example Response

<ResponseExample>
  ```json Success theme={null}
  {
    "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..."
  }
  ```
</ResponseExample>

## Webhook Security

<Warning>
  ### 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.
</Warning>

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 Augustus.

## Error Responses

<ResponseExample>
  ```json Error - Invalid URL theme={null}
  {
    "error": {
      "code": "invalid_endpoint_url",
      "message": "The provided endpoint URL is invalid. Must be a valid HTTPS URL.",
      "type": "validation_error"
    }
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json Error - Invalid Event Types theme={null}
  {
    "error": {
      "code": "invalid_event_types",
      "message": "One or more event types are not supported",
      "type": "validation_error"
    }
  }
  ```
</ResponseExample>

## Next Steps

After creating a webhook subscription:

1. **Test the webhook**: Use the [trigger test webhook](/webhook-subscription/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](/webhook-subscription/list-webhook-subscriptions) endpoint to monitor delivery status

## Related

* [List webhook subscriptions](/webhook-subscription/list-webhook-subscriptions)
* [Update a webhook subscription](/webhook-subscription/update-a-webhook-subscription)
* [Trigger test webhook](/webhook-subscription/trigger-test-webhook)