---
title: "Create a webhook"
method: POST
path: "/webhooks"
tags: ["webhook"]
---

# Create a webhook

`POST /webhooks`

Subscribes a `target_url` to one or more events. Ringover will `POST` the payload of each subscribed event to that URL.

The response contains the `uuid` of the webhook, which you then use to read, update or delete it, and the `signing_key` to verify the signature of the deliveries you receive.

**Re-posting a target URL that is already subscribed is not an error**: the events of the request are **merged** into the existing subscription, and the same `uuid` is returned. Use this to add events idempotently when you do not know the current state.

Creating your first webhook also turns webhook delivery on, so there is nothing to activate in the dashboard beforehand.

**Permission:** No specific permission required. A valid API key is sufficient.

**Monitoring:** Not needed. The webhook is created in the configuration attached to your API key.

## Request body

- RequestNewWebhookSubscription
  - `target_url` string, uri, required — The URL Ringover will POST the subscribed events to (mandatory).
  - `events` WebhookEvent[], required — The events to subscribe `target_url` to (mandatory, at least one, no duplicates).

## Response `201`

Webhook created — returns the resulting subscription.

- WebhookSubscription
  - `uuid` string, uuid, required — The identifier of the webhook: an RFC 4122 v5 UUID derived from `target_url` in the URL namespace. The same target URL always yields the same identifier, and it is stable for the lifetime of the subscription.
  - `target_url` string, uri, required — The URL Ringover POSTs the subscribed events to. Immutable.
  - `events` WebhookEvent[], required — The events delivered to `target_url`, in catalog order.
  - `signing_key` string — The key used to sign the deliveries sent to your endpoints (see *Securing your webhooks* in the `webhook` tag description). Read-only and shared by every subscription of your configuration. Absent while no key has been generated yet.

## Other responses

- `400` — The payload is malformed — `target_url` is missing or is not a valid URL, `events` is empty, or one of the events is not part of the catalog
- `401` — Authentication token is missing, invalid, or expired
- `403` — The API key is not allowed to manage webhooks
- `500` — Internal server error

---

[API](https://skmtc.net/ringover/apis/ringover-public-api.md) · [All operations](https://skmtc.net/ringover/apis/ringover-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ringover/ringover-public-api/revisions/9da73dd2f99e/schema)