---
title: "Create webhook subscription"
method: POST
path: "/webhooks/subscribe"
tags: ["Webhooks"]
---

# Create webhook subscription

`POST /webhooks/subscribe`

## Request

- Base URL: `https://riskmodels.app/api`
- URL: `https://riskmodels.app/api/webhooks/subscribe`
- Auth: HTTP bearer

Register an HTTPS URL for outbound events (e.g. `batch.completed`). The `secret` is returned once in the response; store it to verify `X-RiskModels-Signature` (HMAC-SHA256).

## Request body

- object
  - `url` string, uri, required: Must use https://
  - `events` string[], required
  - `active` boolean
  - `secret` string: Optional custom secret; otherwise server-generated.

## Response `201`

Created; `secret` included in body for verification.

- object
  - `subscription` object
    - `id` string, uuid
    - `url` string, uri
    - `events` string[]
    - `active` boolean
    - `created_at` string, date-time
    - `secret` string

## Other responses

- `400`: Invalid URL or body.
- `401`: Unauthorized.
- `500`: Server error.

---

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