Skip to main content

Webhooks

Webhooks allow your system to receive information about events within your organization as they occur and respond in a way that you define.

Vindral uses HTTP POST to send webhook events to your system as a JSON payload. The payload contains information about the event, such as the event type and the data associated with the event.

Enable Webhooks​

You can enable and configure your webhooks in the Vindral Portal. Navigate to the following URL to access the webhooks settings: Vindral Portal

Here, you can add a new webhook by providing a callback URL where the webhook events will be sent.

Channel events​

Channel events are specific occurrences related to a channel within your organization. Currently, we support the following events:

  • channel.ingest.started
  • channel.ingest.stopped

When such an event occurs, a HTTP POST payload is sent to the webhook's configured URL endpoint.

Delivery headers​

HTTP POST payloads that are delivered to your webhook's configured URL endpoint will contain a signature header x-signature. This is the HMAC hex digest of the request body, and is generated using the SHA-256 hash function and the secret as the HMAC key.

Verifying x-signature​

To verify the x-signature in Node.js, you can use the crypto module's createHmac method. Here's an example:

const crypto = require('crypto')

// Get real secret from Vindral Portal
const secret = "1e265b0d-0ba2-4672-960c-cbfb9a02e003"

function verifySignature(req) {
  const signature = req.headers['x-signature']

  const calculatedSignature = crypto
    .createHmac("sha256", secret)
    .update(JSON.stringify(req.body))
    .digest("hex")

  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(calculatedSignature))
}

Event payload​

Here's an example of a channel event payload:

{
  "id": "75db6597-579c-4e0b-8183-6ea9a45c0e6e",
  "version": 1,
  "event": "channel.ingest.started",
  "timestamp": "2023-12-01T07:42:54.063Z",
  "data": {
    "channelId": "vindral_demo1_ci_099ee1fa-80f3-455e-aa23-3d184e93e04f"
  }
}
  • id - A unique identifier for the event.
  • version - The version of the event payload structure.
  • event - The type of event that occurred. This can be either channel.ingest.started or channel.ingest.stopped, indicating the start and stop of the ingest process respectively.
  • timestamp - The time when the event occurred, in ISO 8601 format.
  • data - An object containing additional data about the event. In this case, it contains a channelId field, which is the identifier of the channel related to the event.

Handling Webhook Failures​

If a webhook delivery fails, we will retry the delivery up to three times. If all retries fail, no further delivery attempts will be made. The resent event will have the same id as the original event. This allows you to identify and ignore duplicate events, preventing the same event from being processed multiple times