Documentation

Support

Vivox Core SDK

Vivox Core SDK

Channel webhooks

Learn how to set up Vivox channel webhooks for monitoring.
Read time 2 minutesLast updated a day ago
Set up channel webhooks to monitor when Vivox channels go active or inactive.

Create channel webhooks

Follow these steps to set up a new webhook:
  1. Navigate to the Vivox Events section of the Unity Dashboard.
  2. Add your endpoint and secret key.
  3. Select Active Channels as the event type.
When events occur, Vivox sends webhook requests to your endpoint with an X-Unity-Signature header containing an HMAC-SHA256 signature of the request body. To verify that the webhook is authentic, compute the HMAC-SHA256 of the request body using your secret key and compare it to the value in the X-Unity-Signature header.

Webhook notifications

After setup, webhook notifications are sent when Vivox channels become active or go inactive. The notifications are sent to the endpoint as POST requests with the following request body: 
{    "channel_uri": "sip:confctl-g-issuer.channel_name.unity_env_id@domain.vivox.com",    "action": "activated",    "timestamp": "2024-01-29T15:45:30Z",    "issuer": "some-issuer",    "project_id": "unity-project-id"}
Store the 
channel_uri
and timestamp in the service that handles these webhooks. Webhook events are sent through a pub/sub that doesn't guarantee message order. When receiving a notification, have the service check if the activated/deactivated timestamp is greater than the last updated timestamp before activating or deactivating the channel to be sure it has the most up to date information.

Active channels resync endpoint

The channel webhooks resync endpoint triggers a resync of all active channels. When this endpoint is called for a Unity project, the Vivox server pushes webhook notifications for every active channel that maps to the project, including each channel’s originally created timestamp. This endpoint has a rate limit of 1 request per minute by IP. It's recommended to only use this endpoint when a resync is necessary because it will push a high volume of events to the webhook endpoint provided by the user.

Authentication

The channel webhooks resync endpoint uses Unity service accounts for authentication. The required service account role for this API is 
Multiplayer/Vivox Channel Admin
.

Webhook breakdown

POST

Uses the base URL of 
https://vivox.services.api.unity.com
 
/channel/v1/organizations/{organizationId}/projects/{projectId}/webhooks/trigger-resync

Path parameters

The webhook uses the following parameters: 
  • organizationId
    : the ID of the Unity organization.
  • projectId
    : the ID of the Unity project.

Sample call

curl --location --request POST 'https://vivox.services.api.unity.com/channel/v1/organizations/:organizationId/projects/:projectId/webhooks/trigger-resync' --user <unity-service-account-key-id>:<unity-service-account-secret-key>'

Output

The following output responses are available:
  • 202: Accepted
{   "msg": "success"}
  • 401
    • Error response. This error is raised in the following scenarios:
      • Invalid service account.
  • 403
    • Error response. This error is raised in the following scenarios:
      • Service account missing permissions.
      • The organization does not have access to the project.
  • 404: Not found
    • Error response. This error is raised in the following scenarios:
      • ProjectID not found
  • 500
    • Error response. A server error was encountered while processing the request.