> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signa.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Webhook Endpoint

> Register a URL that receives signed alert/event POSTs

## Overview

Registers a webhook endpoint and returns the signing `secret` **once** in
the response. Store the secret immediately; subsequent list/retrieve
responses redact it.

Required scope: `portfolios:manage`.

## Body Parameters

<ParamField body="url" type="string" required>
  HTTPS endpoint (HTTP is allowed in non-production environments only).
  Max 2048 chars.
</ParamField>

<ParamField body="description" type="string">Optional human-readable description (max 2000 chars).</ParamField>

<ParamField body="enabled_events" type="string[]" required>
  1--20 event types. The only customer-subscribable event today is
  `alert.created`. Any other value returns `400`. `webhook.test` is
  delivered only when you call [`POST /v1/webhooks/{id}/test`](/api-reference/monitoring/webhooks/test)
  \-- you cannot subscribe to it.
</ParamField>

<ParamField body="metadata" type="object">Free-form metadata.</ParamField>

## Response

<ResponseField name="id" type="string">Endpoint ID (`whk_*`).</ResponseField>
<ResponseField name="object" type="string">Always `"webhook_endpoint"`.</ResponseField>
<ResponseField name="url" type="string">Echo of input.</ResponseField>
<ResponseField name="description" type="string | null">Echo of input.</ResponseField>
<ResponseField name="enabled_events" type="string[]">Echo of input.</ResponseField>
<ResponseField name="status" type="string">`active` or `disabled`.</ResponseField>
<ResponseField name="secret_version" type="integer">Starts at `1`.</ResponseField>
<ResponseField name="secret" type="string">Plaintext signing secret. **Returned only on this response and on rotate-secret.**</ResponseField>
<ResponseField name="consecutive_failures" type="integer">`0` on create.</ResponseField>
<ResponseField name="last_success_at" type="string | null">Null on create.</ResponseField>
<ResponseField name="last_failure_at" type="string | null">Null on create.</ResponseField>
<ResponseField name="metadata" type="object">Echoed back.</ResponseField>
<ResponseField name="created_at" type="string">ISO timestamp.</ResponseField>
<ResponseField name="updated_at" type="string">ISO timestamp.</ResponseField>
<ResponseField name="request_id" type="string">Request identifier.</ResponseField>

## Errors

* **400** — invalid URL, unknown event type, or HTTP URL in production.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.signa.so/v1/webhooks" \
    -H "Authorization: Bearer $SIGNA_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: create-prod-webhook-2026-06-12" \
    -d '{
      "url": "https://acme.example.com/signa-webhook",
      "description": "prod alerts",
      "enabled_events": ["alert.created"]
    }'
  ```

  ```ts TypeScript theme={null}
  const wh = await signa.webhooks.create({
    url: 'https://acme.example.com/signa-webhook',
    description: 'prod alerts',
    enabled_events: ['alert.created'],
  });
  // IMPORTANT: store wh.secret now — it will not be returned again.
  await secretsManager.put('SIGNA_WEBHOOK_SECRET', wh.secret);
  ```
</RequestExample>