---
title: "Create webhook subscription"
method: POST
path: "/v1/webhook_subscriptions"
tags: ["Webhook Subscriptions"]
---

# Create webhook subscription

`POST /v1/webhook_subscriptions`

## Request

- Base URL: `https://api.augustus.com`
- URL: `https://api.augustus.com/v1/webhook_subscriptions`
- Auth: HTTP bearer

Creates a new webhook subscription.

## Headers

- `Idempotency-Key` string, required

## Request body

- CreateWebhookSubscriptionBodyDto
  - `url` string, uri, required: The HTTPS URL where webhook events will be delivered.
  - `events` string[], required: Event types to subscribe to. Use ["*"] for all events.
  - `metadata` object, nullable: Set of up to 50 key-value string pairs you can attach to store structured information, such as correlating this resource with an object in your own system. Keys may be up to 40 characters and values up to 500 characters.

## Response `200`

Success

- WebhookSubscriptionResourceDto
  - `id` string, required: Unique identifier of the webhook subscription.
  - `type` 'webhook_subscription', required: Resource type discriminator.
  - `url` string, required: The HTTPS URL where webhook events are delivered.
  - `events` string[], required: Event types this subscription receives.
  - `metadata` object, required: Set of up to 50 key-value string pairs you can attach to store structured information, such as correlating this resource with an object in your own system. Keys may be up to 40 characters and values up to 500 characters.
  - `created_at` string, date-time, required: ISO 8601 UTC timestamp when the subscription was created.
  - `updated_at` string, date-time, required: ISO 8601 UTC timestamp when the subscription was last updated.

## Changes

- **2026-10-16** `f7ded6c181ab`: 1 info
  - endpoint added
- **2026-08-19** `3d21138daf4c`: 1 breaking
  - added the pattern `^https:\/\/.*` to the request property `url`
- **2026-07-29** `e5198bf3cf7e`: 2 warning, 2 info
  - added the new `account_holder.active` enum value to the `events/items/` response property for the response status `200`
  - added the new `account_holder.closed` enum value to the `events/items/` response property for the response status `200`
  - added the new `account_holder.active` enum value to the request property `events/items/`
  - added the new `account_holder.closed` enum value to the request property `events/items/`
- **2026-07-27** `1d6de495a31d`: 1 breaking
  - the `header` request parameter `Idempotency-Key` became required
- **2026-04-23** `f04b2c330a67`: 3 warning, 3 info
  - added the new `conversion.completed` enum value to the `events/items/` response property for the response status `200`
  - added the new `conversion.created` enum value to the `events/items/` response property for the response status `200`
  - added the new `conversion.failed` enum value to the `events/items/` response property for the response status `200`
  - added the new `conversion.completed` enum value to the request property `events/items/`
  - …2 more

[Operation history](https://skmtc.dev/augustus/apis/ivy-api/changes/v1/webhook_subscriptions/post.md)

---

[API](https://skmtc.dev/augustus/apis/ivy-api.md) - [All operations](https://skmtc.dev/augustus/apis/ivy-api/llms.txt) - [OpenAPI document](https://skmtc.dev/augustus/apis/ivy-api/revisions/e87bdcac11cc?raw)