# Register webhook endpoint

Register a new webhook endpoint to receive event notifications.

Important: The webhook secret is only returned once at creation time.
Store it securely for signature verification.

Endpoint: POST /v1/webhooks/endpoints
Version: 2.0.0
Security: oAuth2

## Request fields (application/json):

  - `url` (string, required)
    Example: "https://partner.example/webhooks/kaito"

  - `secret` (string,null)
    Secret used for signature validation (HMAC-SHA256).
If omitted, Kaito will generate one and return it once at creation time.

  - `events` (array, required)
    Example: ["payment.succeeded","payout.completed"]

## Response 201 fields (application/json):

  - `endpoint` (object, required)

  - `endpoint.endpointId` (string, required)
    Example: "whk_01JH..."

  - `endpoint.url` (string, required)

  - `endpoint.events` (array, required)

  - `endpoint.enabled` (boolean)

  - `endpoint.createdAt` (string, required)

  - `secret` (string, required)
    Returned only once. Store securely.
    Example: "whsec_XXXX"

## Response 400 fields (application/json):

  - `traceId` (string, required)
    Correlation id for troubleshooting
    Example: "trc_01JH8K5P3V9M2K5Q7W6J3Z1A9B"

  - `error` (object, required)

  - `error.code` (string)
    Example: "INVALID_REQUEST"

  - `error.message` (string)
    Example: "Invalid webhook URL"

  - `error.details` (object)


## Response 401 fields