---
title: "Create a webhook subscription"
method: POST
path: "/api/service/webhook-subscription/create"
tags: ["Webhook-Subscription"]
---

# Create a webhook subscription

`POST /api/service/webhook-subscription/create`

Creates a webhook subscription that sends various events from Ivy to a specified url. There can be multiple subscriptions per app.

## Request body

- CreateRequestDto
  - `url` string, required — The endpoint where webhook events are sent.
  - `events` string[] — The events to subscribe the url to.

## Response `200`

Returns the new webhook subscription.

- CreateResponseDto
  - `id` unknown, required
  - `merchant` unknown, required
  - `merchantApp` unknown, required
  - `url` string, required
  - `events` string[], required
  - `createdAt` unknown, required
  - `updatedAt` unknown, required

## Changes

- **2025-11-12** `fd2fa66d08ac` — 3 warning, 4 info
  - added the new `fx.failed` enum value to the `events/items/` response property for the response status `200`
  - added the new `fx.initiated` enum value to the `events/items/` response property for the response status `200`
  - added the new `fx.succeeded` enum value to the `events/items/` response property for the response status `200`
  - the `events` request property default value changed from `test, merchant_updated, merchant_app_updated, order_created, order_updated, refund_succeeded, refund_failed, refund.initiated, refund.succeeded, refund.failed, payout_report_requested, data_session_completed, checkout_session_created, checkout_session_updated, checkout_session_expired, checkout_session_completed, payout_created, payout_updated, user_payout.initiated, user_payout.failed, user_payout.paid, payout.initiated, payout.failed, payout.paid, deposit.received, return.initiated, return.succeeded, return.failed, return.returned` to `test, merchant_updated, merchant_app_updated, order_created, order_updated, refund_succeeded, refund_failed, refund.initiated, refund.succeeded, refund.failed, payout_report_requested, data_session_completed, checkout_session_created, checkout_session_updated, checkout_session_expired, checkout_session_completed, payout_created, payout_updated, user_payout.initiated, user_payout.failed, user_payout.paid, payout.initiated, payout.failed, payout.paid, deposit.received, return.initiated, return.succeeded, return.failed, return.returned, fx.initiated, fx.succeeded, fx.failed`
  - …3 more
- …earlier changes not shown

[Full history](https://skmtc.dev/augustus/apis/ivy-api/changes/api/service/webhook-subscription/create/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-service-production.skmtc.workers.dev/v1/apis/augustus/ivy-api/revisions/59707ad8c8bb/schema)