---
title: "Create Webhook"
method: POST
path: "/api/v2/webhooks"
tags: ["Webhooks"]
---

# Create Webhook

`POST /api/v2/webhooks`

Creates a new webhook for the authenticated team.

## Request body

- WebhookInput — Webhook create/update body. `body`, `headers`, and `queryParams` only take effect for services that issue a templated HTTP request (`generic`, `incidentio`). The `slack` service posts a fixed payload to its incoming-webhook URL and ignores them, so supplying any of these fields on a `slack` webhook is rejected. `headers` and `queryParams` are write-only — they are accepted here but never returned by any read endpoint, so secrets such as auth tokens do not leak. On update (PUT), omitted readable fields (`description`, `body`) are cleared, while omitted `headers`/`queryParams` are preserved — send an explicit `{}` to clear them. Exception: if the destination (`url` or `service`) changes, omitted `headers`/`queryParams` are cleared rather than preserved, so stored secrets are never forwarded to a new destination; re-supply them for the new destination.
  - `name` string, required — Webhook name. Must be unique per service within the team.
  - `service` 'slack' | 'incidentio' | 'generic', required — Webhook service type.
  - `url` string, uri, required — Webhook destination URL.
  - `description` string — Webhook description, shown in the UI.
  - `body` string — Optional request body template. Only for generic/incidentio; rejected for slack.
  - `headers` object — Write-only. Custom HTTP headers sent with the webhook request. Never returned on read. Only for generic/incidentio; rejected for slack. Each value is capped at 4096 characters.
  - `queryParams` object — Write-only. Query parameters appended to the webhook URL. Never returned on read. Only for generic/incidentio; rejected for slack. Each value is capped at 4096 characters.

## Response `200`

Successfully created webhook

- WebhookResponseEnvelope
  - `data` union
    - SlackWebhook
      - `id` string, required — Webhook ID
      - `name` string, required — Webhook name
      - `service` 'slack', required — Webhook service type
      - `url` string — Slack incoming webhook URL
      - `description` string — Webhook description, shown in the UI
      - `updatedAt` string, date-time, required — Last update timestamp
      - `createdAt` string, date-time, required — Creation timestamp
    - IncidentIOWebhook
      - `id` string, required — Webhook ID
      - `name` string, required — Webhook name
      - `service` 'incidentio', required — Webhook service type
      - `url` string — incident.io alert event HTTP source URL
      - `description` string — Webhook description, shown in the UI
      - `updatedAt` string, date-time, required — Last update timestamp
      - `createdAt` string, date-time, required — Creation timestamp
    - GenericWebhook
      - `id` string, required — Webhook ID
      - `name` string, required — Webhook name
      - `service` 'generic', required — Webhook service type
      - `url` string — Webhook destination URL
      - `description` string — Webhook description, shown in the UI
      - `body` string — Optional request body template
      - `updatedAt` string, date-time, required — Last update timestamp
      - `createdAt` string, date-time, required — Creation timestamp

## Other responses

- `400` — Bad request or duplicate webhook
- `401` — Unauthorized
- `403` — Forbidden

## Changes

- **2026-07-08** `6f4381730123` — 1 info
  - endpoint added
- **2026-01-30** `ed852374c451` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/hyperdxio/apis/hyperdx-external-api/changes/api/v2/webhooks/post.md)

---

[API](https://skmtc.dev/hyperdxio/apis/hyperdx-external-api.md) · [All operations](https://skmtc.dev/hyperdxio/apis/hyperdx-external-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/hyperdxio/hyperdx-external-api/revisions/3399efdca551/schema)