---
title: "POST /v1/principals/{id}/endpoints"
method: POST
path: "/v1/principals/{id}/endpoints"
---

# POST /v1/principals/{id}/endpoints

`POST /v1/principals/{id}/endpoints`

## Request

- The document declares no server URL.
- Auth: one of:
  - HTTP bearer
  - API key in cookie `__Secure-better-auth.session_token`

Register a webhook endpoint on a principal. The secret is shown once.

## Path parameters

- `id` string, required

## Request body

- EndpointCreate
  - `url` string, required: Must be **https** — anything else answers 422. Query strings, paths and fragments are legal (integrations route and authenticate with them); only the scheme is policed, because a signed delivery over cleartext would still expose the event body and the signature.

## Response `201`

The request has succeeded and a new resource has been created as a result.

- PrincipalEndpointCreated: Carries the signing secret **once**, as a **Standard Webhooks** `whsec_` value — so a consumer verifies with an off-the-shelf library rather than hand-rolling HMAC against our prose. Every delivery carries `webhook-id`, `webhook-timestamp` and `webhook-signature: v1,<base64>` over `${id}.${timestamp}.${body}`, keyed by the DECODED bytes of this secret. The founder hands it to the agent, and no read on this surface ever produces it again. Delivery health (the engine's circuit breaker) is not reported here — a tripped endpoint is re-armed by deleting and re-creating it, or by any change to the principal's endpoints or grants.
  - `id` string, required
  - `url` string, required
  - `createdAt` string, date-time, required
  - `secret` string, required: The signing secret, returned **once**.

## Other responses

- `default`: An unexpected error response.

---

[API](https://skmtc.dev/foundermail/apis/org.md) - [All operations](https://skmtc.dev/foundermail/apis/org/llms.txt) - [OpenAPI document](https://skmtc.dev/foundermail/apis/org/revisions/8bbb36e378ab?raw)