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
​
status
enum<string>
Chat current statusAvailable 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'));

​
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.