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

# Create a webhook

`POST /webhooks`

## Headers

- `ApiKey` string, required
- `MerchantId` string, required
- `Environment` 'live' | 'sandbox', required

## Request body

- CreateWebhookDto
  - `url` string, required — Fully qualified url, starting with https://, of the webhook endpoint.
  - `events` string[], required — The list of events to enable for this endpoint.
  - `description` string — An optional description of what the webhook is used for.
  - `metadata` object — Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

## Response `201`

- WebhookDtoAlias
  - `id` string, required — Unique identifier for the Webhook
  - `createdAt` string, required — Datetime in UTC timezone at which this object was created. Follows the [Datetime ISO](https://en.wikipedia.org/wiki/ISO_8601).
  - `updatedAt` string, required — Datetime in UTC timezone at which this object was updated. Follows the [Datetime ISO](https://en.wikipedia.org/wiki/ISO_8601).
  - `mode` 'live' | 'sandbox', required — Mode in which this Webhook exists. The sandbox mode can be used during the integration phase and is available as soon as the merchant account is created. No real transactions are made in this mode. The live mode has to be used to make real transactions.
  - `description` string — An optional description of what the webhook is used for.
  - `events` string[], required — The list of events to enable for this endpoint.
  - `metadata` object, required — Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
  - `secret` string — The endpoint’s secret, used to generate webhook signatures. Only returned at creation.
  - `status` 'enabled' | 'disabled', required — The webhook status
  - `url` string, required — Fully qualified url of the webhook endpoint.

## Other responses

- `401` — Wrong credentials
- `500` — Internal error

---

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