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

# Create a webhook subscription

`POST /api/v1/webhooks`

## Request

- Base URL: `https://api.textbee.dev`
- URL: `https://api.textbee.dev/api/v1/webhooks`
- Auth: API key in header `x-api-key`

textbee POSTs the events you pick to your delivery URL and signs each request with your signing secret, sent as the X-Signature header. Failed deliveries are retried up to 10 times, and a subscription that keeps failing is paused.

## Request body

- CreateWebhookDto
  - `name` string: Label shown in the dashboard. Up to 64 characters.
  - `deliveryUrl` string, required: URL textbee POSTs events to. Must be http or https and publicly reachable. Private and loopback hosts are rejected.
  - `signingSecret` string, required: Shared secret, at least 20 characters. textbee signs every delivery with it and sends the signature in the X-Signature header, so your endpoint can verify the request really came from textbee.
  - `events` string[], required: Events to deliver. At least one is required.

## Response `201`

The subscription was created.

- WebhookResponseDTO
  - `data` WebhookSubscriptionDTO, required
    - `_id` string, required: Subscription id.
    - `user` string, required: Owner account id.
    - `name` string: Label shown in the dashboard.
    - `isActive` boolean, required: Whether deliveries are attempted. textbee pauses subscriptions that keep failing.
    - `events` string[], required: Events this subscription receives.
    - `deliveryUrl` string, required: URL events are POSTed to.
    - `signingSecret` string, required: Secret used to sign deliveries.
    - `successfulDeliveryCount` number, required: Deliveries that succeeded.
    - `deliveryFailureCount` number, required: Deliveries that failed.
    - `deliveryAttemptCount` number, required: Delivery attempts made, retries included.
    - `lastDeliveryAttemptAt` string, date-time: Last time a delivery was attempted.
    - `lastDeliverySuccessAt` string, date-time: Last time a delivery succeeded.
    - `lastDeliveryFailureAt` string, date-time: Last time a delivery failed.
    - `notes` WebhookNoteDTO[]: Notes textbee added, such as an auto-pause reason.
      - `at` string, date-time, required: When the note was added.
      - `text` string, required: What textbee recorded, for example why the subscription was paused.
    - `createdAt` string, date-time, required: When the subscription was created.
    - `updatedAt` string, date-time, required: When it was last updated.

## Other responses

- `400`: The delivery URL is unusable, the signing secret is shorter than 20 characters, the event list is empty or unknown, or you already have the maximum number of subscriptions.
- `401`: Missing, invalid, or revoked API key.

---

[API](https://skmtc.dev/textbee/apis/textbee-api.md) · [All operations](https://skmtc.dev/textbee/apis/textbee-api/llms.txt) · [OpenAPI document](https://skmtc.dev/textbee/apis/textbee-api/revisions/e720417e9514?raw)