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

# Create a webhook

`POST /v1/webhooks`

## Request

- Base URL: `https://api.pomerado.ai`
- URL: `https://api.pomerado.ai/v1/webhooks`
- Auth: HTTP bearer

Create a webhook for your jobs' events and return its signing secret once.

- It receives events for every job you started, from any client: the Dashboard, an MCP client or an API key, except Code editor runs.
- Events: job.needs_input (a job asks a question; the payload has its questions and the page to answer them), job.input_expiring (three minutes left to answer), job.succeeded and job.failed (a job settled), and job.repairing (a repair of a run's tool is under way, and the run ends by maintenance.deadline_at). Without events, it receives all five.
- No event carries a result. Read the result from the job, through the client that started it.
- Deliveries are signed with Standard Webhooks, retried for about 14 minutes, and sent only to public HTTPS addresses.
- Only you can change, test or rotate it; a Business Owner or Admin can also see and delete it. It keeps working if you leave the team.
- You can hold at most 20 webhooks.

## Request body

- object
  - `url` string, required
  - `events` string[]: an array of at least 1 item(s)

## Response `201`

The new webhook and its one-time secret

- WebhookWithSecret
  - `id` string, required: a webhook ID: wh_ and 32 lowercase hex digits
  - `created_by` WebhookCreator, required: The member who made the webhook. Only they can change, test or rotate it, and it carries events for the jobs they can see
    - `user_id` string, required: The member's user ID
    - `email` string, nullable, required: The email they sign in with, or null when the account no longer has it
  - `url` string, required
  - `events` string[], required
  - `status` 'active' | 'disabled', required
  - `disabled_reason` 'manual' | 'gone' | 'unreachable' | 'secret_unreadable', nullable, required: Why a disabled webhook sends nothing: manual (turned off), gone (its receiver answered 410), unreachable (20 failed deliveries in a row) or secret_unreadable (rotate its secret)
  - `created_at` string, required: a string to be decoded into a Date
  - `last_delivery_at` string, required: a string to be decoded into a Date
  - `secret` string, required: The Standard Webhooks signing secret (whsec_…), shown only in this response. Verify each delivery's webhook-signature with it.

## Other responses

- `400`: invalid_request
- `401`: unauthorized, reauthentication_required
- `403`: webhooks_unavailable, forbidden
- `409`: webhook_limit_reached
- `413`: request_too_large
- `500`: internal_error
- `503`: temporarily_unavailable

---

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