---
title: "Register a new webhook endpoint"
method: POST
path: "/webhooks"
tags: ["Webhooks"]
---

# Register a new webhook endpoint

`POST /webhooks`

## Request

- Base URL: `https://thesignup.app/api/v1`
- URL: `https://thesignup.app/api/v1/webhooks`
- Auth: HTTP bearer

Returns the endpoint metadata + a one-time `signingSecret`. Store the secret immediately; subsequent reads do not include it. Free tier allows 1 endpoint, Pro 10, Org 100; the cap returns 402 with an `upgrade_required` payload.

## Request body

- CreateWebhookRequest
  - `url` string, uri, required: HTTPS URL the platform will POST to. Plain HTTP is rejected.
  - `description` string
  - `eventTypes` string[]: Optional subscription filter. Omit or pass an empty array to subscribe to every event type.

## Response `201`

Endpoint registered

- CreateOrRotateWebhookResponse
  - `endpoint` WebhookEndpoint, required
    - `id` string, uuid, required
    - `url` string, uri, required
    - `description` string, nullable, required
    - `eventTypes` string[], required: Subscription filter. Empty array = subscribe to every event type the platform emits today and in the future.
    - `paused` boolean, required
    - `pausedReason` string, nullable, required
    - `pausedAt` string, date-time, nullable, required
    - `consecutiveFailures` integer, required
    - `lastSuccessAt` string, date-time, nullable, required
    - `lastFailureAt` string, date-time, nullable, required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
  - `signingSecret` string, required: Plaintext signing secret. Surfaced exactly once — store it immediately. Subsequent reads only return the endpoint metadata; rotate via `POST /v1/webhooks/{id}/rotate`.

## Other responses

- `400`: Bad request — body or path could not be parsed
- `401`: Unauthenticated — credentials missing, malformed, invalid, or revoked
- `402`: Upgrade required — feature is gated by a higher billing tier
- `422`: Validation failed — request body / query / path is structurally wrong
- `429`: Rate limited or daily ceiling exceeded
- `500`: Internal server error

---

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