---
title: "Create a webhook subscription"
method: POST
path: "/api/v1/webhook_subscriptions"
tags: ["Webhooks"]
---

# Create a webhook subscription

`POST /api/v1/webhook_subscriptions`

## Request

- Base URL: `https://getscaleforge.com`
- URL: `https://getscaleforge.com/api/v1/webhook_subscriptions`
- Auth: HTTP bearer

Subscribes an HTTPS URL to receive signed JSON payloads for selected
ScaleForge events. The response contains a one-time `secret` used
to verify HMAC-SHA256 signatures — store it securely, it is not
retrievable later. Requires scope `webhooks:write`.

## Request body

- object
  - `url` string, uri, required
  - `events` string[], required

## Response `201`

Subscription created

- object
  - `data` object
    - `id` integer
    - `url` string, uri
    - `events` string[]: Event names the subscription receives
    - `active` boolean
    - `created_at` string, date-time
    - `secret` string: HMAC-SHA256 signing secret — shown once

## Other responses

- `422`: Validation failed

---

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