Create Webhook

Register a new webhook endpoint. The response includes a per-webhook signing secret that is returned only this once — store it securely before the response leaves your hands.

Endpoint

POST /v1/webhooks

Weight: 5 Authentication: Required (signed) — see Authentication.

Request body

Name	Type	Mandatory	Description
url	string	YES	Target URL. Must start with https:// and resolve to a publicly reachable host serving a valid TLS certificate. Plain http:// and self-signed certs are rejected.
events	array<string>	YES	Non-empty list of event types to subscribe to. Each entry must be one of the values enumerated in Payload Format or one of the wildcards strategy.*, backtest.*, account.*, *.
description	string	NO	Free-form label, ≤ 200 characters. Helps identify the webhook in the dashboard and list responses.
balance_low_threshold	string	NO	Decimal string. Required only if events includes account.balance_low. Triggers an account.balance_low event whenever any tracked asset's available balance drops below this value. Ignored otherwise.

Response

{
  "id": "wh_2a4f10",
  "url": "https://example.com/pipai-webhook",
  "events": ["strategy.deployed", "strategy.position_opened", "strategy.error", "backtest.job_done"],
  "description": "Production strategy alerts",
  "status": "active",
  "consecutive_failures": 0,
  "last_delivery_at": null,
  "last_success_at": null,
  "created_at": "2026-04-29T12:00:00Z",
  "secret": "k3mB2xQ9rFvT7nLpJhYwS4eUaC1oZ8dRgI6XbN0M",
  "_secret_warning": "Store this secret immediately — it will not be retrievable later."
}

Response fields

Field	Type	Description
id	string	Webhook identifier, format wh_<6-8 hex>.
url	string	The target URL as supplied.
events	array<string>	The list of event types this webhook is subscribed to.
description	string|null	The supplied description, or null if omitted.
status	enum	One of active, paused, broken. New webhooks start as active.
consecutive_failures	integer	Number of consecutive failed deliveries. Always 0 on creation.
last_delivery_at	string|null	ISO 8601 UTC timestamp of the most recent delivery attempt, or null if no event has been delivered yet.
last_success_at	string|null	ISO 8601 UTC timestamp of the most recent successful (2xx) delivery, or null.
created_at	string	ISO 8601 UTC creation time.
secret	string	Opaque base64url string (~40 chars) used to sign every delivery to this webhook. Returned only on creation — subsequent reads will not include it. Store it securely.
_secret_warning	string	Static warning string included as a defensive reminder to capture secret immediately.

Errors

• 400 INVALID_PARAMETER — url is missing, malformed, or uses http:// instead of https://; events is empty or contains an unknown type; description exceeds 200 chars; balance_low_threshold is not a positive decimal.
• 403 INSUFFICIENT_PERMISSION — the API key lacks the webhooks:write scope.
• 409 DUPLICATE_URL — a webhook with this url is already registered on the account.
• 429 LIMIT_REACHED — the account already has 25 webhooks (the per-account maximum). Delete an existing webhook before creating another.

See Errors for the full list.

Example

curl -X POST "https://api.pipai.example/v1/webhooks" \
  -H "X-PipAI-API-Key: $API_KEY" \
  -H "X-PipAI-Timestamp: $TS" \
  -H "X-PipAI-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pipai-webhook",
    "events": [
      "strategy.deployed",
      "strategy.position_opened",
      "strategy.error",
      "backtest.job_done"
    ],
    "description": "Production strategy alerts"
  }'