Webhooks

curl https://app.reflections.ai/v1/webhook_endpoints \
  -H "Authorization: Bearer rk_test_…" \
  -H "Reflections-Version: 2026-10-15" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://northlight.example/webhooks/reflections",
    "events": ["*"],
    "connected": true,
    "description": "Production event handler"
  }'

const endpoint = await fetch("https://app.reflections.ai/v1/webhook_endpoints", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.REFLECTIONS_KEY}`,
    "Reflections-Version": "2026-10-15",
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://northlight.example/webhooks/reflections",
    events: ["*"],
    connected: true,
    description: "Production event handler",
  }),
}).then((r) => r.json());
// Store endpoint.secret now. It is not shown again.

import os, uuid, requests

endpoint = requests.post(
    "https://app.reflections.ai/v1/webhook_endpoints",
    headers={
        "Authorization": f"Bearer {os.environ['REFLECTIONS_KEY']}",
        "Reflections-Version": "2026-10-15",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "url": "https://northlight.example/webhooks/reflections",
        "events": ["*"],
        "connected": True,
        "description": "Production event handler",
    },
).json()
# Store endpoint["secret"] now. It is not shown again.

import { createHmac, timingSafeEqual } from "node:crypto";

const TOLERANCE_SECONDS = 5 * 60;

export function verifyWebhook(
  secret: string, // "whsec_…"
  id: string, // webhook-id header
  timestamp: string, // webhook-timestamp header
  signature: string, // webhook-signature header
  body: string, // the raw request body
): boolean {
  const sent = Number(timestamp);
  if (!Number.isInteger(sent)) return false;
  if (Math.abs(Date.now() / 1000 - sent) > TOLERANCE_SECONDS) return false;

  const key = Buffer.from(secret.slice(secret.indexOf("_") + 1), "base64");
  const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${body}`).digest();

  return signature.split(" ").some((entry) => {
    const [version, value] = entry.split(",");
    if (version !== "v1" || !value) return false;
    const given = Buffer.from(value, "base64");
    return given.length === expected.length && timingSafeEqual(given, expected);
  });
}

// For example, in a handler that receives a standard Request:
export async function POST(req: Request): Promise<Response> {
  const body = await req.text();
  const valid = verifyWebhook(
    process.env.REFLECTIONS_WEBHOOK_SECRET ?? "",
    req.headers.get("webhook-id") ?? "",
    req.headers.get("webhook-timestamp") ?? "",
    req.headers.get("webhook-signature") ?? "",
    body,
  );
  if (!valid) return new Response("invalid signature", { status: 400 });

  const event = JSON.parse(body);
  await queue.push(event); // Process after you respond.
  return new Response(null, { status: 204 });
}

import base64, binascii, hashlib, hmac, time

TOLERANCE_SECONDS = 5 * 60

def verify_webhook(secret: str, msg_id: str, timestamp: str, signature: str, body: bytes) -> bool:
    """secret is "whsec_…"; body is the raw request body as bytes."""
    try:
        sent = int(timestamp)
    except ValueError:
        return False
    if abs(time.time() - sent) > TOLERANCE_SECONDS:
        return False

    key = base64.b64decode(secret.split("_", 1)[1])
    signed = f"{msg_id}.{timestamp}.".encode() + body
    expected = hmac.new(key, signed, hashlib.sha256).digest()

    for entry in signature.split(" "):
        version, _, value = entry.partition(",")
        if version != "v1" or not value:
            continue
        try:
            given = base64.b64decode(value, validate=True)
        except binascii.Error:
            continue
        if hmac.compare_digest(given, expected):
            return True
    return False

# For example, in a Flask view:
# body = request.get_data()
# ok = verify_webhook(os.environ["REFLECTIONS_WEBHOOK_SECRET"],
#                     request.headers["webhook-id"], request.headers["webhook-timestamp"],
#                     request.headers["webhook-signature"], body)