Server Events

Webhooks in the OutRival app allow for real-time notifications about specific events within the application. By providing a Webhook URL and a Webhook Secret, you can configure the OutRival app to call your specified URL during certain events. This enables your application to react and handle updates as they happen.

Configuring Webhooks

To set up webhooks, you need to provide two pieces of information:

Webhook URL: The endpoint URL to which the notifications should be sent.
Webhook Secret: A secret key used to generate a signature for each payload, ensuring the security and integrity of the data being transmitted.

When an event occurs, the OutRival app generates a POST request to the provided Webhook URL. The payload of this request contains information about the event, and the x-signature header contains a signature generated from the payload using the Webhook Secret. This signature must be used to verify that the request is indeed from OutRival.

The payload of the webhook is structured as follows:

event

enum<string>

required

The type of server event.

Available options: status-changed, conversation-updated, function-call

type

enum<string>

required

The type of chat modality.

Available options: VOICE, TEXT, SMS

companionId

string

required

A unique identifier for the companion involved in the event

data

object

required

An object containing event-specific information (Event Data Details)

Event Data Details

messages

array<Message>

required

An array of chat messages

Show Message

role

enum<string>

required

Role of the chat message sender

Available options: bot, user

content

string

Text of the chat message

status

enum<string>

Chat current status

Available options: queued, ringing, in-progress, forwarding, ended

startedAt

string

required

Chat started timestamp

endedAt

string

Chat ended timestamp

endedReason

string

The reason the chat ended

phoneNumber

string

User’s phone number for SMS and Phone Call chats

Security and Verification

To ensure the security of the webhook mechanism, it is crucial to verify the x-signature header in each incoming request. This signature is generated by hashing the payload with the Webhook Secret. Your endpoint should compute the hash with the received payload and the secret you provided when setting up the webhook. If the computed hash matches the x-signature header, the request can be considered authentic and from OutRival.

Here are a few examples of how to verify the signature in different programming languages:

  const express = require('express');
  const crypto = require('crypto');

const app = express();
app.use(express.raw({ type: "*/*", limit: "10mb" })); // Set the encoding for express.raw()

app.post('/your-webhook-endpoint', (req, res) => {
const payload = req.body.toString("utf-8");
const secret = 'your_shared_secret';
const xSignature = req.headers['x-signature'];

    const generatedSignature = crypto.createHmac("sha256", secret).update(payload).digest("hex");

    if (generatedSignature === xSignature) {
      console.log('Signature is valid.');
      res.status(200).send('Signature verified');
    } else {
      console.log('Signature is invalid.');
      res.status(403).send('Invalid signature');
    }

});

app.listen(3000, () => console.log('Server running on port 3000'));

  const express = require('express');
  const crypto = require('crypto');

const app = express();
app.use(express.raw({ type: "*/*", limit: "10mb" })); // Set the encoding for express.raw()

app.post('/your-webhook-endpoint', (req, res) => {
const payload = req.body.toString("utf-8");
const secret = 'your_shared_secret';
const xSignature = req.headers['x-signature'];

    const generatedSignature = crypto.createHmac("sha256", secret).update(payload).digest("hex");

    if (generatedSignature === xSignature) {
      console.log('Signature is valid.');
      res.status(200).send('Signature verified');
    } else {
      console.log('Signature is invalid.');
      res.status(403).send('Invalid signature');
    }

});

app.listen(3000, () => console.log('Server running on port 3000'));

from flask import Flask, request, jsonify
import hmac
import hashlib
import json

app = Flask(__name__)

@app.route('/your-webhook-endpoint', methods=['POST'])
def webhook():
    payload = request.json
    secret = 'your_shared_secret'
    x_signature = request.headers.get('X-Signature')

    generated_signature = hmac.new(secret.encode(), msg=json.dumps(payload).encode(), digestmod=hashlib.sha256).hexdigest()

    if generated_signature == x_signature:
        print('Signature is valid.')
        return jsonify({'message': 'Signature verified'}), 200
    else:
        print('Signature is invalid.')
        return jsonify({'message': 'Invalid signature'}), 403

if __name__ == '__main__':
    app.run(debug=True, port=5000)

from flask import Flask, request, jsonify
import hmac
import hashlib
import json

app = Flask(**name**)

@app.route('/your-webhook-endpoint', methods=['POST'])
def webhook():
payload = request.json
secret = 'your_shared_secret'
x_signature = request.headers.get('X-Signature')

    generated_signature = hmac.new(secret.encode(), msg=json.dumps(payload).encode(), digestmod=hashlib.sha256).hexdigest()

    if generated_signature == x_signature:
        print('Signature is valid.')
        return jsonify({'message': 'Signature verified'}), 200
    else:
        print('Signature is invalid.')
        return jsonify({'message': 'Invalid signature'}), 403

if **name** == '**main**':
app.run(debug=True, port=5000)

<?php

$secret = 'your_shared_secret';
$payload = file_get_contents('php://input');
$xSignature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';

$generatedSignature = hash_hmac('sha256', $payload, $secret);

if (hash_equals($generatedSignature, $xSignature)) {
    http_response_code(200);
    echo 'Signature verified';
} else {
    http_response_code(403);
    echo 'Invalid signature';
}

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;
using System;
using System.IO;
using System.Security.Cryptography;
using System.Text;
using System.Threading.Tasks;

public class VerifySignatureMiddleware
{
private readonly RequestDelegate \_next;

    public VerifySignatureMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        var secret = Encoding.UTF8.GetBytes("your_shared_secret");
        var payload = await new StreamReader(context.Request.Body).ReadToEndAsync();
        context.Request.Body.Position = 0; // Reset the stream for further reading

        var xSignature = context.Request.Headers["X-Signature"].ToString();
        using var hmac = new HMACSHA256(secret);
        var computedSignature = BitConverter.ToString(hmac.ComputeHash(Encoding.UTF8.GetBytes(payload))).Replace("-", "").ToLower();

        if (computedSignature.Equals(xSignature, StringComparison.OrdinalIgnoreCase))
        {
            await _next(context);
        }
        else
        {
            context.Response.StatusCode = 403;
            await context.Response.WriteAsync("Invalid signature");
        }
    }

}

// Extension method used to add the middleware to the HTTP request pipeline.
public static class VerifySignatureMiddlewareExtensions
{
public static IApplicationBuilder UseVerifySignatureMiddleware(this IApplicationBuilder builder)
{
return builder.UseMiddleware<VerifySignatureMiddleware>();
}
}

To use this middleware, add it to your application’s request pipeline in the Startup.cs file:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // Other configurations...

    app.UseVerifySignatureMiddleware();

    // Further configurations...
}

Best Practices

Endpoint Resilience: Ensure your webhook endpoint is designed to handle varying loads and can process requests in a timely manner.
Security: Always verify the x-signature to confirm the authenticity of the incoming requests.
Error Handling: Implement robust error handling to manage different types of payload and potential errors.

For any further questions or assistance with setting up webhooks, please contact our support team.

API Documentation

Endpoints

Configuring Webhooks

Event Data Details

Security and Verification

Best Practices

API Documentation

Endpoints

​Configuring Webhooks

​Event Data Details

​Security and Verification

​Best Practices

Configuring Webhooks

Event Data Details

Security and Verification

Best Practices