Webhooks

What is a webhook?

Webhooks or Zapier, which do I want?

Both deliver the same call data. The difference is who writes the glue code.

You can use both. A Zap and a custom webhook on the same event fire independently, they don't conflict.

Setting up a webhook

The three events

A single webhook can subscribe to any combination, you don't need three separate webhooks unless you want to route them to different URLs.

Event call.completed

Fires after every completed call, receptionist mode, assistant mode, demo mode. Delivered once Relay has transcribed the call and produced the summary (usually within 30–60 seconds of hangup).

Payload includes

Caller phone + name, the number they dialed, duration, billable minutes, call summary, urgency, mode, transcript URL, any booked appointments, and the call's stable identifier.

Common use cases

• Sync to your CRM, upsert a contact, log the call as an activity
• Archive to a data warehouse, BigQuery, Snowflake, Postgres, for analytics
• Trigger your own follow-up flow, drip campaigns, internal routing, lead scoring
• Fan out to multiple systems, your server can decide where each call should go
• Custom alerts, Slack/Teams/Discord with logic Zapier can't easily express

Event call.urgent

Same payload as call.completed, but fires only for calls Relay's classifier flags as urgent. You don't configure the classifier, it reads the transcript and caller tone automatically.

Common use cases

• Page on-call staff, PagerDuty, Opsgenie, or your own paging stack
• SMS or call yourself instantly via Twilio, Vonage, or your own SMS gateway
• Open a high-priority ticket in your help desk with a 30-minute SLA
• Push a notification to a mobile app via FCM or APNs
• Wake a Slack workflow that escalates if nobody acknowledges in N minutes

Event appointment.booked

Fires when Relay books an appointment during a call. (Requires Google Calendar connected in Dashboard → Calendar.) If a single call books multiple appointments, the event fires once per appointment.

Payload includes

Start / end UTC, time zone, caller name, caller phone, stated purpose, the appointment's event ID, and the originating call's SID for cross-referencing.

Common use cases

• Mirror into another calendar system, Outlook, Apple, internal scheduling
• Block the slot in a booking tool, Calendly, Acuity, Cal.com, to prevent double-booking
• Create a CRM deal/opportunity with the appointment attached
• Schedule reminder SMS 24 hours and 1 hour before
• Pre-create video meeting rooms, Zoom, Google Meet, Whereby

Payload reference

Every delivery is a POST with a JSON body in this envelope:

{
  "version": "2026-05-05",
  "event": "call.completed",
  "timestamp": "2026-05-05T14:23:00Z",
  "webhookId": "whk_abc123",
  "data": { ... event-specific fields ... }
}

version is the contract version. We bump it on breaking shape changes, treat unrecognized versions as a signal to update your integration before processing. Additive fields (new optional keys inside data) are not breaking and don't bump the version.

call.completed / call.urgent sample

{
  "version": "2026-05-05",
  "event": "call.completed",
  "timestamp": "2026-05-05T14:23:00Z",
  "webhookId": "whk_abc123",
  "data": {
    "sid": "CA...",
    "tenantId": "tnt_...",
    "caller": "+12125551234",
    "callerName": "John Smith",
    "calledLine": "+18885559876",
    "duration": 142,
    "billableMinutes": 3,
    "startedAt": "2026-05-05T14:20:38Z",
    "endedAt": "2026-05-05T14:23:00Z",
    "endReason": "caller-hangup",
    "summary": "Caller asked about pricing for the team plan...",
    "urgency": "normal",
    "mode": "receptionist",
    "appointmentsBooked": [],
    "transcriptUrl": "https://api.relay.sandybrook.io/api/calls/CA.../transcript",
    "redirect": null
  }
}

appointment.booked sample

{
  "version": "2026-05-05",
  "event": "appointment.booked",
  "timestamp": "2026-05-05T14:23:00Z",
  "webhookId": "whk_abc123",
  "data": {
    "sid": "CA...",
    "tenantId": "tnt_...",
    "eventId": "evt_...",
    "startUtc": "2026-05-07T15:00:00Z",
    "endUtc": "2026-05-07T15:30:00Z",
    "timeZoneId": "America/New_York",
    "callerName": "John Smith",
    "callerPhone": "+12125551234",
    "purpose": "Initial consultation"
  }
}

Signature verification

Verify the signature on every request. Without it, anyone who guesses your URL can send fake call data into your system.

The signature is HMAC-SHA256 over {timestamp}.{rawBody}, the X-Relay-Timestamp header value, a literal period, then the exact raw request body bytes (before any JSON parsing or middleware re-encoding). Compute on your side, constant-time compare. Reject any request older than ~5 minutes (compare the timestamp to your server clock) to prevent replay attacks.

Node.js (Express)

const crypto = require("crypto");
const express = require("express");
const app = express();

// IMPORTANT: capture the raw body for HMAC verification
app.use("/relay-hook", express.raw({ type: "application/json" }));

app.post("/relay-hook", (req, res) => {
  const timestamp = req.header("X-Relay-Timestamp");
  const signature = req.header("X-Relay-Signature");
  const rawBody = req.body; // Buffer

  if (!verify(rawBody, timestamp, signature, process.env.RELAY_WEBHOOK_SECRET)) {
    return res.status(401).send("bad signature");
  }
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    return res.status(401).send("stale timestamp");
  }

  const payload = JSON.parse(rawBody.toString("utf8"));
  // ...do your thing...
  res.status(200).send("ok");
});

function verify(rawBody, timestamp, sigHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  const provided = sigHeader.replace(/^sha256=/, "");
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(provided, "hex"),
  );
}

Python (Flask)

import hmac, hashlib, os, time
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["RELAY_WEBHOOK_SECRET"]

@app.post("/relay-hook")
def relay_hook():
    timestamp = request.headers.get("X-Relay-Timestamp", "")
    signature = request.headers.get("X-Relay-Signature", "")
    raw_body = request.get_data()  # bytes, before JSON parsing

    if not verify(raw_body, timestamp, signature, SECRET):
        abort(401)
    if abs(time.time() - int(timestamp)) > 300:
        abort(401)

    payload = request.get_json()
    # ...do your thing...
    return "ok", 200

def verify(raw_body, timestamp, sig_header, secret):
    payload = f"{timestamp}.{raw_body.decode('utf-8')}".encode()
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    provided = sig_header.removeprefix("sha256=")
    return hmac.compare_digest(expected, provided)

Ruby (Rails)

require "openssl"

class RelayHookController < ApplicationController
  skip_before_action :verify_authenticity_token

  def receive
    raw_body  = request.raw_post
    timestamp = request.headers["X-Relay-Timestamp"]
    signature = request.headers["X-Relay-Signature"]

    return head :unauthorized unless verify(raw_body, timestamp, signature)
    return head :unauthorized if (Time.now.to_i - timestamp.to_i).abs > 300

    payload = JSON.parse(raw_body)
    # ...do your thing...
    head :ok
  end

  private

  def verify(raw_body, timestamp, sig_header)
    expected = OpenSSL::HMAC.hexdigest("sha256", ENV["RELAY_WEBHOOK_SECRET"], "#{timestamp}.#{raw_body}")
    provided = sig_header.to_s.sub(/^sha256=/, "")
    Rack::Utils.secure_compare(expected, provided)
  end
end

Retry and idempotency

Return 2xx within 10 seconds and the delivery is marked successful. Any other status (or no response) and Relay retries on a managed queue:

• Up to 5 attempts total
• Backoff: 30 seconds → 1 hour, exponential
• Max retry duration: 24 hours

Managing your webhooks

Everything lives on Dashboard → Webhooks. Each row has these controls:

Troubleshooting

Common questions