---
title: "Register webhook"
method: POST
path: "/api/v1/webhooks"
tags: ["API v1 — Webhooks"]
---

# Register webhook

`POST /api/v1/webhooks`

## Request

- Base URL: `https://api.rivalize.ai`
- URL: `https://api.rivalize.ai/api/v1/webhooks`
- Auth: HTTP bearer

Register a webhook URL. Returns the signing secret ONCE — store it securely.

## Request body

- object
  - `url` string, uri, required
  - `events` string[], required
  - `min_priority` 'high' | 'medium' | 'low': Default: low
  - `project_id` string, uuid: Scope to a specific project

## Response `201`

Success. The resource is returned in the `data` envelope.

- object: Success. The resource is returned in the `data` envelope.
  - `data` object, required

## Other responses

- `400`: Error. Carries a stable `code`, a human `message`, the HTTP `status`, and the `request_id` (also on the x-request-id response header).
- `409`: Error. Carries a stable `code`, a human `message`, the HTTP `status`, and the `request_id` (also on the x-request-id response header).

---

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