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

# Create a webhook subscription

`POST /webhooks`

Subscribes a public HTTPS URL to a project event. LLM Pulse POSTs a JSON envelope (`event`, `occurred_at`, `project_id`, `subscription_id`, `data`) to the URL every time the event occurs, signed via the `X-LLMPulse-Signature` header (HMAC-SHA256 of the raw body computed with the subscription secret). Failed deliveries are retried 5 times with backoff; subscriptions auto-disable after 20 consecutive failed deliveries. Idempotent for the same project + event + URL. Requires a `read_write` scope API key and the Scale plan or above.

## Request body

- object
  - `project_id` integer, required
  - `event_type` 'mention.created' | 'competitor_mention.created' | 'citation.created' | 'prompt_execution.completed' | 'sentiment.negative_detected' | 'recommendation.completed' | 'intelligence_task.completed', required
  - `target_url` string, required — Public HTTPS URL that will receive signed event payloads

## Response `201`

Created. The signing secret is only returned by this endpoint.

- object
  - `id` integer
  - `project_id` integer
  - `event_type` 'mention.created' | 'competitor_mention.created' | 'citation.created' | 'prompt_execution.completed' | 'sentiment.negative_detected' | 'recommendation.completed' | 'intelligence_task.completed'
  - `target_url` string
  - `disabled` boolean
  - `failure_count` integer
  - `last_delivered_at` string, date-time
  - `created_at` string, date-time
  - `secret` string — HMAC signing secret (whsec_...). Only returned on create.

## Other responses

- `401` — Authentication failed
- `403` — API key lacks write permission
- `404` — Resource not found
- `422` — Invalid parameters

---

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