Webhooks

curl -X POST https://api.get-exo.com/v1/webhooks \
  -H "X-Exo-API-Key: $EXO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/exo",
    "eventTypes": ["contradiction.detected", "belief.superseded"]
  }'

import httpx

response = httpx.post(
    "https://api.get-exo.com/v1/webhooks",
    headers={"X-Exo-API-Key": EXO_KEY},
    json={
        "url": "https://hooks.example.com/exo",
        "eventTypes": ["contradiction.detected", "belief.superseded"],
    },
)
secret = response.json()["secret"]  # shown once, store it now

const response = await fetch("https://api.get-exo.com/v1/webhooks", {
  method: "POST",
  headers: {
    "X-Exo-API-Key": process.env.EXO_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://hooks.example.com/exo",
    eventTypes: ["contradiction.detected", "belief.superseded"],
  }),
});
const { secret } = await response.json(); // shown once, store it now

import hashlib
import hmac
import time


def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    """Verify one Exo webhook delivery. `raw_body` must be the exact bytes."""
    parts = dict(part.split("=", 1) for part in header.split(","))
    timestamp, signature = int(parts["t"]), parts["v1"]

    # Reject deliveries outside the replay window.
    if abs(time.time() - timestamp) > tolerance:
        return False

    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

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

export function verify(
  rawBody: Buffer,
  header: string,
  secret: string,
  toleranceSeconds = 300,
): boolean {
  const parts = Object.fromEntries(
    header.split(",").map((part) => {
      const index = part.indexOf("=");
      return [part.slice(0, index), part.slice(index + 1)];
    }),
  );
  const timestamp = Number(parts.t);
  const signature = parts.v1;

  // Reject deliveries outside the replay window.
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;

  const expected = createHmac("sha256", secret)
    .update(Buffer.concat([Buffer.from(`${timestamp}.`), rawBody]))
    .digest("hex");

  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(signature, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

# There is no cURL equivalent: verification happens in your receiver, not in a
# request you send. To check your implementation end to end, ask Exo to send a
# signed test event and inspect what your endpoint received.
curl -X POST https://api.get-exo.com/v1/webhooks/$WEBHOOK_ID/test \
  -H "X-Exo-API-Key: $EXO_KEY"