Webhooks

Overview

When integrating the Vatis Streams API you may need to listen to events on your resources, so your application can react accordingly. To do this, you can register a webhook endpoint containing the URL where you want to receive the events and the type of events the endpoint is listening to. When an event is triggered, a POST request will be sent to all the registered endpoints with the event data.

Setup

Manage your webhooks through the API Dashboard.

Webhook structure

The webhook endpoint you can define will have the following structure:

{
  "id": "<string>",
  "url": "<string>",
  "events": [
    "<string>"
  ],
  "enabled": true,
  "description": "<string>"
}

Property	Description
`id`	The webhook endpoint identifier
`url`	The URL where the events will be sent. Accepted protocols: `HTTP`, `HTTPS`
`events`	The list of event types the endpoint is listening to. Check the avaiable event types here
`enabled`	Indicates if the webhook is enabled. You can disable an endpoint to temporarily stop receiving requests to the endpoint
`description`	An optional description of the webhook

Local IP addresses and loopback interfaces are not allowed in the url

Event structure

The webhook event you’ll receive will have the following structure:

{
  "id": "<string>",
  "type": "<string>",
  "webhookEndpointId": "<string>",
  "timestamp": "<long>",
  "payloadSchema": "<string>",
  "payload": "<object>"
}

Property	Description
`id`	The event identifier
`type`	The event type. Check the avaiable event types here
`webhookEndpointId`	The webhook endpoint identifier
`timestamp`	The event timestamp in milliseconds since epoch. Use this to prevent replay attacks
`payloadSchema`	The fully qualified name of the payload schema
`payload`	The event payload

Event types

Event type	Supports dynamic webhooks	Description
`stream.ready`	yes	The stream has just been created and is ready to receive data
`stream.completed`	yes	The stream completed successfully
`stream.failed`	yes	The stream failed
`stream.expired`	yes	The stream storage time expired and it was deleted
`group.created`	yes	A new group has been created
`group.completed`	yes	All the streams in the group completed successfully. This event will be emitted again if a new stream joins the group and completes
`group.failed`	yes	All the streams in the group finished and at least one stream failed. This event will be emitted again if a new stream joins the group and fails
`group.expired`	yes	The group storage time expired and it was deleted. A group will expire only after all the streams in the group had expired
`group.stream-joined`	yes	A new stream has joined the group
`gateway.connected`	no	A client connected to the stream gateway
`gateway.disconnected`	no	The client disconnected from the stream gateway
`gateway.closed`	no	The gateway of the stream is permanently closed
`gateway.error`	no	The gateway of the stream is permanently closed due to an error
`processor.running`	no	The stream processor has been assigned to stream and it is running
`processor.completed`	no	The stream processor has been completed successfully
`processor.error`	no	The stream processor has failed

Source IPs

To make sure your server is able to receive the events, you can whitelist the following IP addresses:

Europe: 52.59.67.134

Redelivery

If the server does not respond with a 2xx status code, the event redelivery will be retried for the next three hours with an exponential backoff strategy.

Development

For experimenting the webhook integration on a local environment, you can create the setup described below.

Setup steps

Install ngrok

 curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null && echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | sudo tee /etc/apt/sources.list.d/ngrok.list && sudo apt update && sudo apt install ngrok

Alternatively, you can download the executable from the official website

Install Nginx

apt install nginx

Configure Nginx

cat <<EOF > /etc/nginx/conf.d/dev-webhook.conf
server {
  listen 8081;
  server_name localhost;

  location /200 {
    add_header Content-Type text/plain;
    return 200 "200 - OK";
  }

  location /400 {
    add_header Content-Type text/plain;
    return 400 "400 - ERROR";
  }

  location /500 {
    add_header Content-Type text/plain;
    return 500 "500 - SERVER ERROR";
  }
}

Prepare the tunnel

nginx
ngrok http 8081

Create/update the webhook

Create or update the webhook endpoint URL with the temporary URL provided by ngrok. Choose one of the following as URL paths, based on the test you want to perform:

/200
/400
/500

Monitor requests

Open the Ngrok dashboard at http://localhost:4040 to monitor the requests. Create a new stream or group to trigger the events.

Considerations

A user can define up to 20 webhook endpoints
The same event may be sent multiple times to the same endpoint
The order of the events is not guaranteed

Dynamic webhooks

A dynamic webhook is a webhook defined on a resource basis. In contrast to a standard webhook that is defined once and can be triggered by any resource (group, stream, gateway, etc.) based on the event key, a dynamic webhook is associated with a specific resource and it can be triggered only by that resource. The main advantage of a dynamic webhook is the ability to modify the endpoint URL for each created stream. For example, we can include a unique identifier in the endpoint URL that changes for each created stream.

All gateways

For each available gateway, a dynamic webhook can be defined as a query parameter that follows this general syntax: webhook[.RESOURCE[.STATE]]=<url> For example:

webhook.stream.completed=https://mydomain.com/success will create a dynamic webhook the receives the stream.completed event at the https://mydomain.com/success URL
webhook.stream.completed=https://mydomain.com/success&webhook.stream.failed=https://mydomain.com/fail will create two dynamic webhooks, one that will be triggered by the stream.completed event at the https://mydomain.com/success URL, and the other that will receive the stream.failed event at the https://mydomain.com/fail URL
webhook.stream.completed=https://mydomain.com/status&webhook.stream.failed=https://mydomain.com/status will create a single dynamic webhook that will be triggered by both stream.completed and stream.failed events at the https://mydomain.com/status URL
webhook.stream=https://mydomain.com/stream-event is a wildcard dynamic webhook that be triggered by any stream-related event at the https://mydomain.com/stream-event URL
webhook=https://mydomain.com/any-event is a wildcard dynamic webhook that will be triggered by any event at the https://mydomain.com/any-event URL

Websocket Gateway

Additionally to the dynamic webhooks defined using query parameter, the WebSocket Gateway can receive the dynamic webhooks configuration using the Configuration Message. The general form of the webhook configuration is as follows:

{
  "type": "CONFIGURATION",
  "webhook": {
    "https://mydomain.com/success": ["stream.completed"],
    "https://mydomain.com/fail": ["stream.failed"],
    "https://mydomain.com/status": ["stream.completed", "stream.failed"],
    "https://mydomain.com/stream-event": ["stream.*"],
    "https://mydomain.com/any-event": ["*"]
  }
}

Please use either the query parameters or the configuration message for defining the dynamic webhooks. If both are specified, the behaviour is undefined.

Limitations

Only stream and group resources can be used in dynamic webhooks
No more than 3 dynamic wehooks can be defined
The supported endpoint protocols are http and https

Vatis Docs

Speech to Text

Audio Intelligence

Infrastructure

Integration

Overview

Setup

Webhook structure

Event structure

Event types

Source IPs

Redelivery

Development

Considerations

Dynamic webhooks

All gateways

Websocket Gateway

Limitations

Vatis Docs

Speech to Text

Audio Intelligence

Infrastructure

Integration

​Overview

​Setup

​Webhook structure

​Event structure

​Event types

​Source IPs

​Redelivery

​Development

​Considerations

​Dynamic webhooks

​All gateways

​Websocket Gateway

​Limitations

Overview

Setup

Webhook structure

Event structure

Event types

Source IPs

Redelivery

Development

Considerations

Dynamic webhooks

All gateways

Websocket Gateway

Limitations