Receive Bliro events in your webhook endpoint

Bliro Webhooks allow organizations to automate the handling of call data by receiving real-time notifications whenever a call is processed. This is the case once the first for a call is generated. With Bliro Webhooks, your backend systems can automatically trigger follow-up actions, enhancing workflow automation.

How Bliro Webhooks Work

Scope: Webhooks operate at the organization level. Any call processed by a member of the organization will trigger the webhook.
Trigger Event: Webhooks are triggered once the transcription is finalized and a summary is generated for a call.
Delivery Method: Bliro sends a POST request with a JSON payload to the specified webhook endpoint over HTTPS.
Security: An optional Bliro-Signature header is available for securing webhook events using HMAC generation based on a timestamp and payload.

Bliro-Signature Format:

Bliro-Signature:
t=1492774577,
v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Managing Webhooks

Bliro Webhooks can be managed via the Webhooks section in the organization settings:

Navigate to Webhooks Settings:
- Go to app.bliro.io/orgs/settings/webhooks.
Create a New Webhook:
- Click on "Create Webhook".
- Enter Webhook Details:
  - Webhook Name: Provide a recognizable name.
  - Webhook URL: Must support HTTPS (TLS encryption required).
  - Security Token (Optional): If provided, Bliro will generate an HMAC signature.
- Newly created webhooks are deactivated by default.
Edit, Delete, Activate, or Deactivate Webhooks:
- Webhooks can be managed at any time from the Webhooks settings page.
Test the Webhook:
- Before activating a webhook, click the "Test Webhook" button to ensure the endpoint can handle payloads properly.

Creating a Webhook Endpoint

To receive webhook events from Bliro, you need to set up an HTTPS endpoint that can accept POST requests.

Key Requirements:

Must accept POST requests with a JSON payload.
Must return a 2xx HTTP status code promptly to acknowledge receipt.
Should verify the Bliro-Signature if a security token is used.

Example Webhook Endpoint in Node.js:

const express = require('express');
const crypto = require('crypto');
const app = express();
app.use(express.json());

const verifySignature = (payload, signature, secret) => {
  const timestamp = payload.timestamp;
  const data = `${timestamp}.${JSON.stringify(payload.data)}`;
  const hmac = crypto.createHmac('sha256', secret).update(data).digest('hex');
  return hmac === signature;
};

app.post('/bliro/webhook', (req, res) => {
  const payload = req.body;
  const signature = req.headers['bliro-signature'];
  const secret = process.env.BLIRO_SECRET;

  if (secret && !verifySignature(payload, signature, secret)) {
    return res.status(400).send('Invalid signature');
  }

  console.log(`Received event: ${payload.event_type}`);
  res.status(200).send('Received');
});

app.listen(4242, () => console.log('Webhook endpoint listening on port 4242'));

Manual Verification of Webhook Signatures

To verify webhook signatures manually:

Extract Timestamp and Signature:
- Parse the Bliro-Signature header to retrieve the timestamp (t) and signature (v1).
Prepare the Signed Payload:
- Concatenate the timestamp, a period (.), and the JSON payload.
Generate HMAC SHA256 Hash:
- Compute the hash using the security token as the key and a combination of timestamp and signed payload as the message.
Compare Signatures:
- Ensure the generated hash matches the v1 value from the header.

Testing Your Webhook

Before activating a webhook in Bliro

Click "Test Webhook" in the Webhooks settings page.
Monitor the Endpoint Response:
- Ensure that a 200 OK response is returned.
- Check logs for the receipt of the test payload.

Activating Your Webhook

Once testing is successful:

Return to the Webhooks settings page.
Toggle the activation switch next to the tested webhook.
Bliro will now send all relevant event data to the endpoint.

Best Practices for Using Bliro Webhooks

Handle Events Asynchronously

Process incoming events with an asynchronous queue.
This approach avoids endpoint overwhelm during high traffic periods (e.g., monthly subscription renewals).

Exempt Webhook Routine from CSRF Protection

If your web framework uses CSRF protection, exempt the webhook route to avoid blocking legitimate requests.

Receive Events with an HTTPS Server

The endpoint must support HTTPS with a valid TLS certificate.
Bliro webhooks support only TLS versions 1.2 and 1.3.

Secure Your Endpoint

Use HMAC signature verification to ensure events originate from Bliro.
Handle timestamps properly to prevent replay attacks.

Troubleshooting

Commin Issues

400 Error (Bad Request): Check endpoint acceptance for POST requests and correct JSON payload handling.
500 Error (Internal Server Error): Review server logs for unexpected errors.
TLS Errors: Confirm the server supports TLS 1.2 or higher.
Timeouts: Ensure fast response times; process heavy logic asynchronously.

Conclusion

By setting up Bliro Webhooks, your organiuation can streamline the handling of call summaries by triggering automated processes. Secure your integration by verifying signatures manually or using built-in methods, using HTTPS, and handling payloads asynchronously. For further assistance, contact [email protected]