---
title: "Create a webhook subscription (admin only)"
method: POST
path: "/v1/webhooks"
tags: ["Webhooks"]
---

# Create a webhook subscription (admin only)

`POST /v1/webhooks`

## Request

- Base URL: `https://app.getdealboard.com`
- URL: `https://app.getdealboard.com/v1/webhooks`
- Auth: HTTP bearer

For `generic` provider webhooks, the response includes a one-time `signingSecret` — capture it; the secret cannot be retrieved later.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `boardId` string, uuid, required
  - `url` string, required
  - `label` string, nullable
  - `events` string[], required
  - `stageFilter` string[]: Stage IDs (from this board) to filter stage_changed events. Empty = all stages.

## Response `201`

Created

- object
  - `id` string, uuid, required
  - `boardId` string, uuid, required
  - `label` string, nullable, required
  - `urlFingerprint` string, required: Last 4 characters of the URL. The URL itself is a secret and is never returned.
  - `provider` 'slack' | 'teams' | 'discord' | 'generic', required
  - `events` string[], required
  - `stageFilter` string[], required: Stage IDs (per-board) to filter `deal.stage_changed` events to. Empty = all stages.
  - `active` boolean, required
  - `createdAt` string, date-time, required
  - `lastDeliveredAt` string, date-time, nullable, required
  - `lastError` string, nullable, required
  - `signingSecret` string, nullable: Non-null only for `generic` provider. Shown exactly once.

## Other responses

- `400`: Invalid URL or input.
- `403`: Admin role required.

---

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