Skip to main content
POST
/
v1
/
webhooks
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"]
  }'

{
  "id": "<string>",
  "object": "<string>",
  "url": "<string>",
  "description": {},
  "enabled_events": [
    "<string>"
  ],
  "status": "<string>",
  "secret_version": 123,
  "secret": "<string>",
  "consecutive_failures": 123,
  "last_success_at": {},
  "last_failure_at": {},
  "metadata": {},
  "created_at": "<string>",
  "updated_at": "<string>",
  "request_id": "<string>"
}

​
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

​
url
string
required
HTTPS endpoint (HTTP is allowed in non-production environments only). Max 2048 chars.
​
description
string
Optional human-readable description (max 2000 chars).
​
enabled_events
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 — you cannot subscribe to it.
​
metadata
object
Free-form metadata.

​
Response

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

​
Errors

  • 400 — invalid URL, unknown event type, or HTTP URL in production.
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"]
  }'