webhook

Add events to a webhook

Changed on

Adds events to a webhook, keeping the ones it is already subscribed to. The resulting set is the union of both, so re-sending an event that is already subscribed has no effect.

To unsubscribe events, send the desired list to PUT /webhooks/{webhookId}/events.

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.

patch/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