Channel webhooks
Learn how to set up Vivox channel webhooks for monitoring.
Read time 2 minutesLast updated 6 months ago
Set up channel webhooks to monitor when Vivox channels go active or inactive.
Note
Channel webhooks are an enterprise-only feature. To enable this feature, contact a Vivox representative.
Create channel webhooks
Follow these steps to set up a new webhook.
- Navigate to the Vivox Events section of the Unity Dashboard.
- Add your endpoint and secret key.
- 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"}
Note
The possible action types are and .
activateddeactivatedStore the 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.
channel_uriActive 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 AdminWebhook 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:
- : the ID of the Unity organization.
organizationId - : the ID of the Unity project.
projectId
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.
- Error response. This error is raised in the following scenarios:
- 403
- Error response. This error is raised in the following scenarios:
- Service account missing permissions.
- The organization does not have access to the project.
- Error response. This error is raised in the following scenarios:
- 404: Not found
- Error response. This error is raised in the following scenarios:
- ProjectID not found
- Error response. This error is raised in the following scenarios:
- 500
- Error response. A server error was encountered while processing the request.