POST /v1/firm-control/webhooks
operationId: createWebhook
Registers a webhook endpoint. The signing secret is returned once in this response and never again.
Headers
| Header | Notes |
|---|---|
X-Firm-ID | Firm UUID. Auto-injected for firm API keys. |
Body
| Field | Required | Notes |
|---|---|---|
url | yes | HTTPS endpoint. |
description | no | Free-form label. |
event_types | no | Array of event types from the event catalog. |
Example
curl -X POST "$TRADARA_BASE_URL/v1/firm-control/webhooks" \
-H "X-Tradara-Api-Key: $TRADARA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.acme.example/tradara",
"description": "primary ops sink",
"event_types": ["accounts.updated", "accounts.locked", "risk.breach"]
}'
Response — 201 Created
{
"id": "whk_01HW...",
"firm_id": "8f4a1d6e-2b1c-4e9a-9d3b-5e6c7a0d1f23",
"url": "https://hooks.acme.example/tradara",
"description": "primary ops sink",
"event_types": ["accounts.updated", "accounts.locked", "risk.breach"],
"status": "ACTIVE",
"created_by_user_id": "usr_01HW...",
"last_delivery_at": null,
"created_at": "2026-06-26T16:00:00Z",
"updated_at": "2026-06-26T16:00:00Z",
"secret": "whsec_8e9...c1"
}
secret is shown only in this response. Store it now — you’ll need it to validate Tradara-Signature headers.Errors
| HTTP | Meaning |
|---|---|
400 | Missing url or invalid event type. |
502 | Downstream webhook service unreachable. |