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>"
}

​

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>"
}

​

Event types

​

Source IPs

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

• 18.194.212.83
• 3.120.9.38
• 3.68.55.77

​

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.

 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

apt install 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";
  }
}

nginx
ngrok http 8081

​

Considerations

1. A user can define up to 20 webhook endpoints
2. The same event may be sent multiple times to the same endpoint
3. 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": ["*"]
  }
}

​

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