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

# Create a new Webhook

`POST /v1/webhooks`

Note: Webhooks on a development domain (mockable.io, ngrok-free.app, ngrok-free.dev, on.aws, onrender.com, run.app, webhook.site) are automatically deleted when delivery returns a 404, 410, or 501 response. They are also deleted after retries are exhausted on a persistent connection error (timeout, DNS failure, connection refused, or a recognized persistent TLS certificate failure).

## Request body

- WebhookCreate
  - `description` string, required
  - `scopes` WebhookResource[], nullable — One or more resources to fire webhooks for. Available resources include comments, companies, engagements, milestones, requests, users. If `null`, webhooks will fire for all resources.
  - `url` string, uri, required

## Response `201`

The newly created Webhook

- object
  - `data` WebhookReadWithSecret, required
    - `uuid` string, uuid, required — The unique ID for the webhook, referenced as `webhook_uuid` in webhook requests
    - `description` string, required — A human-readable description of the webhook's use
    - `scopes` WebhookResource[], nullable, required — One or more resources to fire webhooks for. Available resources include comments, companies, engagements, milestones, requests, users. If `null`, webhooks will fire for all resources.
    - `url` string, uri, required
    - `created_at` string, date-time, required
    - `secret` string, required — A 20-character secret used for HMAC signing

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden (requires scopes `webhooks:write`)
- `429` — Too many requests

---

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