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 Data Details

​

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>();
}
}

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.