---
title: "Register a webhook"
method: POST
path: "/api/v1/webhooks"
tags: ["Webhooks"]
---

# Register a webhook

`POST /api/v1/webhooks`

Creates a new webhook. Webhooks are registered per `merchant_code` and per environment:
the environment is determined by the secret key you authorize the request with —
a production key (`sk_...`) registers webhooks for production payments, a test key
(`sk_test_...`) registers webhooks for test payments. Each `merchant_code` + key pair
can have up to 4 webhooks.

## Headers

- `X-Merchant-Code` string, required

## Request body

- WebhookRegistration
  - `url` string, uri, required — HTTPS endpoint for notifications. The URL should be valid and accessible (not local).
  - `header` object
    - `title` string — Arbitrary header name to sign the request.
    - `value` string — Random string to sign the request.

## Response `200`

Success. Webhook object is returned.

- WebhookRegistrationResponse
  - `header` object, nullable
    - `title` string, nullable — Arbitrary header name to sign the request.
    - `value` string, nullable — Random string to sign the request.
  - `id` string — Unique webhook ID, assigned by Tabby.
  - `is_test` boolean, required — Deprecated. The webhook environment is determined by the secret key used at registration (production `sk_...` or test `sk_test_...`), not by this field.
  - `url` string, uri, required — HTTPS endpoint for notifications. The URL should be valid and accessible (not local).

## Other responses

- `400` — One of the required fields is missing or request is not formatted correctly.
- `401` — The request cannot be authorized.
- `404` — You are using an incorrect ID.
- `500` — Something bad happened. We're notified.

---

[API](https://skmtc.dev/tabby/apis/tabby-api-reference.md) · [All operations](https://skmtc.dev/tabby/apis/tabby-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/tabby/tabby-api-reference/revisions/cff62a2a6ee9/schema)