POST `/api/v1/webhooks`

Add a webhook (the signing secret is returned once).

Scope webhooks:write
Idempotency-Key
operationId webhooksCreate

Adds a webhook: Vestoris will POST the chosen events to your HTTPS endpoint, signed with a secret that is returned only in this answer: store it now. Every delivery carries Vestoris-Signature: t=<unix>,v1=<HMAC-SHA256(secret, "t.body")>; refuse timestamps older than 5 minutes. Send a test with POST /webhooks/{id}/ping. How to verify the signature: Webhooks.

The token needs the scope webhooks:write, and the person or service account behind it needs the matching privileges and account permissions, exactly as on the screens. See Scopes.

Idempotency-Key. Send a unique Idempotency-Key (up to 255 characters, e.g. a UUID) with every POST. Retrying with the same key and body replays the first answer for 24 hours, so a timeout never creates a second order; the same key with a different body is refused (idempotency_key_reused).

Request

POST /api/v1/webhooks

Headers

Header	Required	Value
`Authorization`	yes	`Bearer <token>`: an OAuth access token (`vat_…`) or a personal access token (`vpt_…`). Get a token
`Idempotency-Key`	yes	A unique string up to 255 characters (a UUID). Idempotency
`Content-Type`	yes	`application/json`

Body: `WebhookIn`

Field	Type	Required	Description
`url`	string	no	Your HTTPS endpoint (public address).
`events`	list of string	no	Event types to send.
`status`	string	no	"active" or "paused".
`description`	string	no	A note for you.
`rotate_secret`	boolean	no	True to get a new signing secret (shown once).

Decimals (money, prices, quantities, percentages) are sent as strings, ids as strings, times as ISO 8601 UTC.

Examples

Keep the token in an environment variable (VESTORIS_TOKEN), never in the script.

curl

curl -X POST "https://vestoris.com/api/v1/webhooks" \
  -H "Authorization: Bearer $VESTORIS_TOKEN" \
  -H 'Idempotency-Key: 7f9c2b1e-4d0a-4a7e-9a51-3c2f0b8d6e11' \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/vestoris","events":["fill.created","violation.created"],"description":"Fills to the risk system"}'

Python (requests)

import os, requests

r = requests.post(
    "https://vestoris.com/api/v1/webhooks",
    headers={
        "Authorization": f"Bearer {os.environ['VESTORIS_TOKEN']}",
        "Idempotency-Key": "7f9c2b1e-4d0a-4a7e-9a51-3c2f0b8d6e11",
    },
    json={
        "url": "https://hooks.example.com/vestoris",
        "events": [
            "fill.created",
            "violation.created"
        ],
        "description": "Fills to the risk system"
    },
    timeout=30,
)
r.raise_for_status()  # errors are application/problem+json with a stable "code"
print(r.json())

JavaScript (fetch)

const res = await fetch("https://vestoris.com/api/v1/webhooks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VESTORIS_TOKEN}`,
    "Idempotency-Key": "7f9c2b1e-4d0a-4a7e-9a51-3c2f0b8d6e11",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
      "url": "https://hooks.example.com/vestoris",
      "events": [
          "fill.created",
          "violation.created"
      ],
      "description": "Fills to the risk system"
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.code}: ${data.detail}`); // problem+json
console.log(data);

Response

201 Created, application/json: WebhookCreated. Rate-limit headers: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset.

Response fields

Field	Type	Description
`id`	id (string)	The record's id (a string of digits).
`url`	string	Your HTTPS endpoint.
`events`	list of string	Event types to send (see the webhook guide).
`status`	string	The status.
`description`	string	A note for you.
`failing_deliveries`	integer	Deliveries currently failing.
`created_at`	date-time or null	When it was created.
`last_delivery_at`	date-time or null	When the last delivery was tried.
`secret`	string or null	The signing secret, shown only in this answer.
`secret_note`	string	A reminder that the secret is shown once.

Example response

HTTP/1.1 201 Created
Content-Type: application/json

{
    "id": "2",
    "url": "https://hooks.example.com/vestoris",
    "events": [
        "fill.created",
        "violation.created"
    ],
    "status": "active",
    "description": "Fills to the risk system",
    "failing_deliveries": 0,
    "created_at": "2026-10-27T14:30:00Z",
    "last_delivery_at": null,
    "secret": "whsec_…",
    "secret_note": "Shown once. Store it now."
}

Example values. Your values depend on your firm's data; prices, orders and fills are simulated.

Status codes and errors

Errors are application/problem+json (RFC 9457) with a stable code to program against; the detail says what to fix. See Errors.

Status	When	Problem codes
201	Created
200 / 201	The same Idempotency-Key again: the first answer is replayed (24 hours)
400	The request is malformed	`invalid_request` `invalid_json`
401	No token, or it is invalid or expired	`invalid_token`
403	The token lacks the scope, or the person or service account behind it lacks the privilege or account permission	`insufficient_scope` `forbidden` `ip_not_allowed`
409	Not possible in the current state	`invalid_transition` `conflict` `idempotency_in_progress`
422	Validation failed (the detail says which field), or blocked	`validation_failed` `idempotency_key_reused`
428	A required header is missing	`idempotency_key_required`
429	Rate limited: wait for Retry-After seconds	`rate_limited`

{
    "type": "https://vestoris.com/developers/errors#validation_failed",
    "title": "Validation failed",
    "status": 422,
    "detail": "Quantity must be greater than zero.",
    "code": "validation_failed",
    "instance": "/api/v1/webhooks"
}

On the screens

The same thing in the app is explained in:

API clients and webhooks

POST /api/v1/webhooks