---
title: "Add a webhook endpoint"
method: POST
path: "/v1/projects/{projectId}/webhooks"
tags: ["Webhooks"]
---

# Add a webhook endpoint

`POST /v1/projects/{projectId}/webhooks`

## Request

- Base URL: `https://hootlens-api-368877148687.us-east1.run.app`
- URL: `https://hootlens-api-368877148687.us-east1.run.app/v1/projects/{projectId}/webhooks`
- Auth: HTTP bearer

Adds an https address that receives the chosen events, signed in the Standard Webhooks format. The address must be on port 443 and resolve to public addresses only (400 otherwise). The answer carries the signing secret (`whsec_...`) once; it cannot be shown again. 429 at the limit or when adding too fast, 503 when the server cannot seal secrets. Needs an owner or editor; personal access tokens receive 403.

Required token scopes are listed in x-hootlens-scopes. A signed-in person needs the matching permission on the site instead (the viewer and editor roles are presets of the permissions).

## Path parameters

- `projectId` string, required: An identifier: 1 to 80 letters, digits, underscores or hyphens.

## Request body

- WebhookInput
  - `url` string, required
  - `label` string
  - `events` string[], required

## Response `201`

The endpoint and its secret.

- object
  - `endpoint` WebhookEndpoint, required
    - `id` string, required: An identifier: 1 to 80 letters, digits, underscores or hyphens.
    - `url` string, uri, required
    - `label` string
    - `events` string[], required
    - `createdAt` integer, required: Epoch milliseconds.
    - `secretRotatedAt` integer: Epoch milliseconds.
    - `enabled` boolean, required
    - `disabledAt` integer: Epoch milliseconds.
    - `disabledReason` 'manual' | 'failures': failures: switched off after sustained failure.
    - `consecutiveFailures` integer, required
    - `lastSuccessAt` integer: Epoch milliseconds.
    - `lastFailureAt` integer: Epoch milliseconds.
    - `lastStatus` integer: The last HTTP status the endpoint answered with.
  - `secret` string, required: Shown once.

## Other responses

- `400`: The request fields are invalid.
- `401`: The credential is missing, expired or revoked.
- `403`: The credential or the person's permissions on the site do not permit this action.
- `404`: The site, or the record inside it, does not exist or the caller is not a member (a non-member cannot tell the two apart).
- `429`: A rate limit or a per-site limit was reached.

---

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