webhook

Replace the events of a webhook

Changed on

Replaces the whole set of events delivered to a webhook. Events that are not in the request are unsubscribed, so this is the operation to use when your integration owns the full list.

To add events without knowing the current list, use PATCH /webhooks/{webhookId}/events instead.

The target URL is immutable, so the uuid of the webhook does not change.

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

Monitoring: Not needed.

put/webhooks/{webhookId}/events

Request

  • Base URL
    https://public-api.ringover.com/v2
  • URL
    https://public-api.ringover.com/v2/webhooks/{webhookId}/events
  • Auth
    API key in header Authorization

Path parameters

webhookIdstring uuid required
Example:bc5c5a41-44c5-5b7c-a521-45bf56d82cbe

The identifier of the webhook, as returned in the uuid field.

Request body

eventsWebhookEvent[] required

The events to apply to the subscription (mandatory, at least one, no duplicates).

Example request

{
  "events": [
    "call.missed",
    "call.voicemail"
  ]
}

Response

Successful operation — returns the updated 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 call, message and fax 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",
  "event_signing_keys": {
    "contact.call": "3f9a1c7e2b8d4f6a0e5c9b1d7a3f2e8c4b6d0a19",
    "contact.search": "8e2d4b6f1a9c3e7d5b0f2a4c6e8d1b3f5a7c9e02"
  }
}

Changes

  • 1d700a84e7b0Revision changes
    • warning

      added the new sms.delivery_receipt enum value to the / response property for the response status

    • info

      added the new sms.delivery_receipt enum value to the request property /

  • 9e23e47609a5Revision changes
    • warning

      added the new contact.call enum value to the / response property for the response status

    • warning

      added the new contact.search enum value to the / response property for the response status

    • info

      added the new contact.call enum value to the request property /

    • info

      added the new contact.search enum value to the request property /

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status