Sign in
latestOpenAPI 3.1.1Proprietary – Contact us for usage terms2026-08-20173183551.4 KB

9da73dd2f99e

webhook

Create a webhook

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.

post/webhooks

Request body

target_urlstring uri required

The URL Ringover will POST the subscribed events to (mandatory).

eventsWebhookEvent[] required

The events to subscribe target_url to (mandatory, at least one, no duplicates).

Example request

{
  "target_url": "https://api.example.com/webhooks/ringover",
  "events": [
    "call.started",
    "call.answered",
    "call.ended"
  ]
}

Response

Webhook created — returns the resulting subscription.

uuidstring 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_urlstring uri required

The URL Ringover POSTs the subscribed events to. Immutable.

eventsWebhookEvent[] required

The events delivered to target_url, in catalog order.

signing_keystring

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.

Example response

{
  "uuid": "bc5c5a41-44c5-5b7c-a521-45bf56d82cbe",
  "target_url": "https://api.example.com/webhooks/ringover",
  "events": [
    "call.started",
    "call.answered",
    "call.ended"
  ],
  "signing_key": "b7c1f2e4a9d84c3f8e5b6a7d9c0e1f23"
}