---
title: "Create a webhook endpoint"
method: POST
path: "/v1/webhooks/applications/{appId}/endpoints"
tags: ["Webhook"]
---

# Create a webhook endpoint

`POST /v1/webhooks/applications/{appId}/endpoints`

## Request

- Base URL: `https://api.prod.keyban.io`
- URL: `https://api.prod.keyban.io/v1/webhooks/applications/{appId}/endpoints`
- Auth: API key in header `X-Api-Key`

Register an HTTPS endpoint to receive event deliveries. A signing secret (`whsec_…`) is generated and returned ONCE in the response — store it now; it is never retrievable again. The receiver verifies the `webhook-signature` header with it (Standard Webhooks).

## Path parameters

- `appId` string, required

## Request body

- CreateWebhookEndpointDto
  - `url` string, uri, required: Absolute HTTPS URL that receives the POST deliveries. HTTP is rejected; private, loopback and link-local hosts and cloud metadata endpoints are blocked server-side (SSRF protection).
  - `eventTypes` string[], required: Event types this endpoint subscribes to. A delivery is sent only when the event type is in this list.
  - `enabled` boolean, required: When false, no delivery is sent — the endpoint (and its secrets) are kept so it can be re-enabled later.

## Response `201`

The created endpoint, including its signing secret (shown once)

- WebhookEndpointWithSecretDto
  - `id` string, uuid, required: Entity UUID
  - `createdAt` string, date-time, required: Creation date (ISO 8601)
  - `updatedAt` string, date-time, required: Last update date (ISO 8601)
  - `applicationId` string, uuid, required: Application (tenant) that owns this endpoint.
  - `url` string, uri, required: HTTPS URL that receives the deliveries.
  - `eventTypes` string[], required: Event types this endpoint is subscribed to.
  - `enabled` boolean, required: Whether deliveries are currently sent to this endpoint.
  - `secret` string, required: Standard Webhooks signing secret (`whsec_<base64>`). Returned ONCE at creation or rotation and never again — store it now. The receiver verifies the `webhook-signature` header with it (e.g. the `standardwebhooks` library).

---

[API](https://skmtc.dev/keyban/apis/keyban-rest-apis.md) · [All operations](https://skmtc.dev/keyban/apis/keyban-rest-apis/llms.txt) · [OpenAPI document](https://skmtc.dev/keyban/apis/keyban-rest-apis/revisions/0bb79a1da961?raw)