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" \
  -d '{
    "url": "https://acme.example.com/signa-webhook",
    "description": "prod alerts",
    "enabled_events": ["alert.created", "webhook.test"]
  }'

{
  "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>"
}

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.

​
Overview

Registers a webhook endpoint and returns the signing secret once in the response (VAL-API-009). 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. Accepted values: alert.created, sync_run.searchable, webhook.test.
​
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" \
  -d '{
    "url": "https://acme.example.com/signa-webhook",
    "description": "prod alerts",
    "enabled_events": ["alert.created", "webhook.test"]
  }'