---
title: "Create Alert Webhook"
method: POST
path: "/api/v2/alert-webhooks"
tags: ["Alerts", "Enterprise"]
---

# Create Alert Webhook

`POST /api/v2/alert-webhooks`

Creates a new alert webhook (channel + webhook + HMAC secret in one
transaction). The generated HMAC secret is returned on this response only.

## Request body

- object — Request body for creating an alert webhook.
  - `type` 'generic' | 'slack' | 'ms-teams', required
  - `name` string, required
  - `description` string
  - `url` string, uri, required — Must be https, http is not supported.

## Response `201`

Created

- object
  - `data` object — Response payload from creating an alert webhook. The newly generated HMAC secret is included on this response only; subsequent reads of the webhook do not expose the secret value.
    - `webhook` ModelAlertWebhook — Alert webhook resource — a joined view of the `alert_channels`, `alert_webhooks` for a single webhook destination. The HMAC secret value is never included in this view; it is only returned at create or rotate time.
      - `id` string, uuid — The channel UUID; also serves as the webhook identifier.
      - `type` 'generic' | 'slack' | 'ms-teams' — Webhook target type.
      - `name` string
      - `description` string
      - `url` string, uri
      - `health` number, double — Rolling health score in [0, 1], where 1 is fully healthy.
      - `attempts` integer — Total dispatch attempts observed for this webhook.
      - `failures` integer — Total failed dispatch attempts observed for this webhook.
      - `last_error` string, nullable
      - `last_errored_at` string, date-time, nullable — An RFC-3339 formatted string
      - `last_succeeded_at` string, date-time, nullable — An RFC-3339 formatted string
      - `created_at` string, date-time
      - `created_by` string
      - `updated_at` string, date-time
      - `updated_by` string
      - `disabled_at` string, date-time, nullable — An RFC-3339 formatted string
      - `disabled_by` string, nullable
    - `hmac_secret` string — Base64-encoded HMAC secret used to sign outbound webhook payloads.

## Other responses

- `400` — **Bad Request** This could be due to one of the following reasons: - JSON payload is missing or malformed - Path or query parameters are missing or invalid/malformed - The data sent is not valid (ex- sending a `string` in an `integer` field)
- `401` — **Unauthorized** This endpoint failed an authentication requirement. Either the client tried to access a protected endpoint without being authenticated, or an auth validation failed (ex- invalid credentials or expired token).
- `403` — **Forbidden** This is most commonly caused by an authenticated client trying to access a resource that it does not have permission for.
- `409` — **Conflict** The supplied `url` collides with an existing alert webhook
- `429` — **Too Many Requests** The client has sent too many requests within a certain time window and tripped the rate limiting middleware.
- `500` — **Internal Server Error** This is usually the result of either an unexpected database or application error. The client may try modifying or resending the request, but the error is likely not related to the client doing something wrong.

---

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