Webhooks (real-time events from Rilla)

{
  "webhook_event_id": "8d3e1c4a-7b2f-4a13-b3a5-2c5d49ce4f10",
  "event_type": "conversation_processed",
  "sent_at": "2026-05-08T19:42:11.418Z",
  "data": {
    "conversation_id": "f1a3e9d8-2b46-4c1a-9c7e-7e4a18d2c93f",
    "organization_id": "1907eddc-64da-4c60-9cc2-f30841635050",
    "conversation_url": "https://app.rillavoice.com/conversations/single?id=f1a3e9d8-2b46-4c1a-9c7e-7e4a18d2c93f",
    "transcript_url": "https://rillavoice-processed-audio.s3.us-east-1.amazonaws.com/1907eddc-64da-4c60-9cc2-f30841635050/c986c3da-30ba-4d07-8fb8-b8ed38ca7241/1780249759000_transcript.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=21600&X-Amz-Signature=EXAMPLE",
    "user_id": "a52b8c7d-3e1f-4a90-9b22-6d18e7f4c521",
    "user_email": "rep@yourcompany.com",
    "recorded_at": "2026-05-08T18:35:00.000Z",
    "recording_duration_seconds": 2143,
    "summary": "Customer expressed interest in the premium package and asked about financing. Rep walked through the 36-month plan and scheduled a follow-up for next week.",
    "custom_insights": "Strong buying signal at 12:30. Pricing objection handled cleanly. Follow-up date confirmed.",
    "surveys": [
      {
        "surveyId": "5e0c3bac-6737-4fdc-a7bc-acbb7f4ccd6f",
        "conversationId": "f1a3e9d8-2b46-4c1a-9c7e-7e4a18d2c93f",
        "surveyName": "Discovery Call Quality",
        "createdAt": "2026-05-08T19:41:55.802Z",
        "data": {
          "rapport_built": "yes",
          "discovery_questions_asked": 7,
          "next_step_confirmed": true
        }
      }
    ],
    "appointment_id": "appt-1234"
  }
}

X-Rilla-Signature: sha256=4f1ce1e3d9a7b2c45e7c1a89f3b4d2e6...

import hmac
import hashlib

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    if not header.startswith("sha256="):
        return False
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header.removeprefix("sha256="))

import { createHmac, timingSafeEqual } from "crypto";

function verify(rawBody, header, secret) {
  if (!header?.startsWith("sha256=")) return false;
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const provided = header.slice("sha256=".length);
  if (expected.length !== provided.length) return false;
  return timingSafeEqual(Buffer.from(expected), Buffer.from(provided));
}

import hmac
import hashlib
from fastapi import FastAPI, Header, HTTPException, Request

app = FastAPI()
SECRET = "your-shared-secret"

@app.post("/rilla/webhook")
async def rilla_webhook(
    request: Request,
    x_rilla_signature: str = Header(None),
):
    raw_body = await request.body()

    if x_rilla_signature is None or not x_rilla_signature.startswith("sha256="):
        raise HTTPException(401, "missing signature")

    expected = hmac.new(SECRET.encode(), raw_body, hashlib.sha256).hexdigest()
    provided = x_rilla_signature.removeprefix("sha256=")
    if not hmac.compare_digest(expected, provided):
        raise HTTPException(401, "bad signature")

    event = await request.json()
    if event["event_type"] == "conversation_processed":
        conversation_id = event["data"]["conversation_id"]
        # ... handle the event idempotently using event["webhook_event_id"] ...

    return {"ok": True}

import express from "express";
import { createHmac, timingSafeEqual } from "crypto";

const app = express();
const SECRET = "your-shared-secret";

// Capture the raw body — express.json() drops it.
app.use(
  express.json({
    verify: (req, _res, buf) => {
      req.rawBody = buf;
    },
  }),
);

app.post("/rilla/webhook", (req, res) => {
  const header = req.header("X-Rilla-Signature") ?? "";
  if (!header.startsWith("sha256=")) return res.status(401).end();

  const expected = createHmac("sha256", SECRET)
    .update(req.rawBody)
    .digest("hex");
  const provided = header.slice("sha256=".length);
  if (
    expected.length !== provided.length ||
    !timingSafeEqual(Buffer.from(expected), Buffer.from(provided))
  ) {
    return res.status(401).end();
  }

  const event = req.body;
  if (event.event_type === "conversation_processed") {
    // ... idempotent processing keyed on event.webhook_event_id ...
  }

  res.status(200).end();
});

curl -i -X POST "https://your-app.example.com/rilla/webhook" \
  -H "Content-Type: application/json" \
  -H "X-Rilla-Signature: sha256=4f1ce1e3d9a7b2c45e7c1a89f3b4d2e6..." \
  -d '{
    "webhook_event_id": "test-event-1",
    "event_type": "conversation_processed",
    "sent_at": "2026-05-08T19:42:11.418Z",
    "data": {
      "conversation_id": "f1a3e9d8-2b46-4c1a-9c7e-7e4a18d2c93f",
      "organization_id": "1907eddc-64da-4c60-9cc2-f30841635050",
      "conversation_url": "https://app.rillavoice.com/conversations/single?id=f1a3e9d8-2b46-4c1a-9c7e-7e4a18d2c93f",
      "transcript_url": null,
      "user_id": "a52b8c7d-3e1f-4a90-9b22-6d18e7f4c521",
      "user_email": "rep@yourcompany.com",
      "recorded_at": "2026-05-08T18:35:00.000Z",
      "recording_duration_seconds": 2143,
      "summary": null,
      "custom_insights": null,
      "surveys": [],
      "appointment_id": null
    }
  }'