---
title: "Create a webhook subscription"
method: POST
path: "/events/subscription"
tags: ["Webhooks"]
---

# Create a webhook subscription

`POST /events/subscription`

Subscribes a callback URL to a webhook event type. Use `GET /events` to discover valid `event_name` values.

## Request body

- object
  - `event_name` string, required — The event type to subscribe to, e.g. `payout.updated`.
  - `callback_url` string, uri, required — The URL to deliver events to.

## Response `201`

The subscription was created.

- object
  - `data` object
    - `subscription` WebhookSubscription
      - `id` string, uuid
      - `eventName` string
      - `callbackUrl` string, uri
      - `createdAt` string, date-time
      - `lastSentAt` string, date-time, nullable
    - `secret` string — Signing secret for verifying deliveries from this subscription. Store it securely.

## Other responses

- `400` — The request was invalid.
- `401` — Missing or invalid API key.

---

[API](https://skmtc.net/trykarat/apis/karat-payout-api.md) · [All operations](https://skmtc.net/trykarat/apis/karat-payout-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/trykarat/karat-payout-api/versions/8941916e3707/schema)