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

# Create a webhook

`POST /v1/webhooks`

## Request

- Base URL: `https://api.hyperresearch.ai`
- URL: `https://api.hyperresearch.ai/v1/webhooks`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `hr_session`

The signing secret is returned once. The URL is checked against the SSRF guard at registration and again at delivery.

## Request body

- CreateWebhookBody
  - `url` string, uri, required
  - `events` union[], required
    - union
      - 'run.clarifying' | 'run.started' | 'run.step' | 'run.blocked' | 'run.done' | 'run.failed' | 'run.aborted' | 'escalation.queued' | 'verify.done' | 'usage.threshold' | 'webhook.test'
      - '*'

## Response `201`

Created

- CreatedWebhook
  - `id` string, required
  - `url` string, required
  - `events` string[], required: The wire values this endpoint is subscribed to. `*` means every event.
  - `display_events` object[], required: The same subscription with a human name for each event ("Run finished", "A source needs your decision"), so a picker never has to show `run.done` (E2E5-08). Same order as `events`; an event this build does not recognise keeps its raw value as its label. The full catalogue, with descriptions, is `GET /v1/webhooks/events`.
    - `event` string, required
    - `label` string, required
  - `active` boolean, required
  - `created_at` string, required
  - `dead_deliveries` integer, required: How many deliveries to this endpoint gave up after exhausting their retries (1 m, 5 m, 30 m, 2 h, 12 h). These are gone: nothing re-sends them. `GET /v1/webhooks/{id}/deliveries` lists them with the status each attempt got back.
  - `secret` string, required

## Other responses

- `400`: Invalid request
- `401`: Authentication failed
- `403`: Insufficient scope or plan
- `404`: Not found
- `429`: Rate limited or over quota
- `500`: Internal error

---

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