> ## 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 it
immediately: list and retrieve responses redact it. A newly created endpoint's `status` is
always `active`.

Requires the `portfolios:manage` scope.

## 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
  [Test Webhook Endpoint](/api-reference/monitoring/webhooks/test); you can't 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">Always `"active"` on create.</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](/api-reference/monitoring/webhooks/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

| Status | `type`             | When                                                                              |
| ------ | ------------------ | --------------------------------------------------------------------------------- |
| 400    | `validation_error` | Invalid URL, unknown event type in `enabled_events`, or an HTTP URL in production |

## Code Examples

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

  ```typescript TypeScript theme={null}
  import { Signa } from "@signa-so/sdk";
  const signa = new Signa({ api_key: process.env.SIGNA_API_KEY });

  const wh = await signa.webhooks.create({
    url: "https://hooks.auroradigital.example.com/signa",
    description: "Production alerts for Aurora Digital",
    enabled_events: ["alert.created"],
  });
  // Store wh.secret in your secrets manager now: it is not returned again.
  console.log(wh.secret);
  ```
</CodeGroup>

<ResponseExample>
  ```json theme={null}
  {
    "id": "whk_2mR8vNkT",
    "object": "webhook_endpoint",
    "url": "https://hooks.auroradigital.example.com/signa",
    "description": "Production alerts for Aurora Digital",
    "enabled_events": ["alert.created"],
    "status": "active",
    "secret_version": 1,
    "secret": "whsec_8f2a1c9e4b7d0a3f6c5e2b1d9a8f7e6c",
    "consecutive_failures": 0,
    "last_success_at": null,
    "last_failure_at": null,
    "metadata": {},
    "created_at": "2026-07-06T08:00:00.000Z",
    "updated_at": "2026-07-06T08:00:00.000Z",
    "request_id": "req_4tYpL2Qn"
  }
  ```
</ResponseExample>

## Related Endpoints

* [Test Webhook Endpoint](/api-reference/monitoring/webhooks/test) - send a synthetic ping before you go live
* [Rotate Webhook Secret](/api-reference/monitoring/webhooks/rotate-secret) - roll the signing secret
* [List Webhook Endpoints](/api-reference/monitoring/webhooks/list) - list your endpoints
* [Webhooks guide](/guides/monitoring/webhooks) - signature verification and delivery behavior