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

## Headers

- `Idempotency-Key` string

## 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

- **2026-04-07** `b58ce3f5ffe3` — 1 breaking
  - removed the required property `apiSurface` from the response with the `200` status
- **2026-04-01** `c2edd9a4d3cf` — 1 info
  - added the required property `apiSurface` to the response with the `200` status
- **2026-03-06** `d617edaf95c0` — 1 info
  - added the new optional `header` request parameter `Idempotency-Key`
- …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/c3055fc06ca3/schema)