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

# Register a webhook endpoint

`POST /api/webhook-endpoints`

## Request

- Base URL: `http://localhost:38200`
- URL: `http://localhost:38200/api/webhook-endpoints`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `token`

Validates the URL against the same SSRF guard used at delivery time (rejects loopback, private ranges, and the cloud metadata address). Returns the signing secret (`X-ContextQ-Signature` HMAC key) **only this once** — no other read ever reveals it, except a subsequent `rotate-secret` call.

## Request body

- object
  - `url` string, required
  - `description` string
  - `eventTypes` LifecycleEventType[]: Empty/omitted subscribes to every lifecycle event type.

## Response `201`

Created endpoint plus the signing secret (shown once).

- WebhookEndpoint: Never includes the encrypted signing secret at rest. `secret` is `null` except on the responses that explicitly reveal it once (create, rotate-secret).
  - `id` integer
  - `tenantId` integer
  - `url` string
  - `description` string, nullable
  - `eventTypes` LifecycleEventType[]: Empty array means "subscribed to every lifecycle event type".
  - `status` 'active' | 'paused' | 'revoked'
  - `secret` string, nullable: Populated only on create and rotate-secret responses.
  - `lastDeliveryAt` string, date-time, nullable
  - `lastDeliveryStatus` string, nullable
  - `lastDeliveryError` string, nullable
  - `createdByUserId` integer, nullable
  - `createdAt` string, date-time
  - `updatedAt` string, date-time

## Other responses

- `400`: Validation failure, invalid/unsafe URL, or invalid input.
- `401`: Missing or invalid credentials.
- `403`: The caller has no resolvable tenant context.

---

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