---
title: "Create webhook endpoint"
method: POST
path: "/v1/webhooks"
tags: ["Webhooks"]
---

# Create webhook endpoint

`POST /v1/webhooks`

## Request

- Base URL: `https://api.predictasiax.com`
- URL: `https://api.predictasiax.com/v1/webhooks`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `app_id` string, required: Owning app id (app_*). Must belong to the caller.
  - `url` string, uri, required: HTTPS delivery endpoint. No userinfo, no fragment.
  - `events` string[], required: Event catalog. Unknown events return WEBHOOK_EVENT_UNKNOWN.
  - `label` string: Optional short label for the webhook.
  - `description` string: Optional longer description.

## Response `200`

Webhook created. Signing secret returned ONCE — store immediately.

- object
  - `data` object
    - `webhook` object
      - `id` string
      - `app_id` string
      - `url` string
      - `events` string[]
      - `active` boolean
      - `label` string, nullable
      - `description` string, nullable
      - `created_at_ms` integer
    - `signing_secret` string: Format whsec_<48hex>. Store this — used to verify HMAC t=,v1= on every delivery. Rotate via POST /v1/webhooks/{id}/rotate-secret.
    - `signing_secret_notice` string
  - `meta` object
    - `ts_ms` integer
    - `trace_id` string

## Other responses

- `400`: VALIDATION_FAILED / WEBHOOK_URL_INVALID / WEBHOOK_EVENT_UNKNOWN
- `401`: AUTH_INVALID
- `403`: SCOPE_MISSING — builder:apps:write required
- `404`: NOT_FOUND — app_id does not exist
- `429`: RATE_LIMITED — webhooks:manage bucket

---

[API](https://skmtc.dev/predictasiax/apis/predictasiax-network-api.md) · [All operations](https://skmtc.dev/predictasiax/apis/predictasiax-network-api/llms.txt) · [OpenAPI document](https://skmtc.dev/predictasiax/apis/predictasiax-network-api/revisions/c2ed1a03ce79?raw)