API reference

Headers on every delivery

X-Xyra-Signature

t=<unix seconds>,v1=<hex HMAC-SHA256>

X-Xyra-Timestamp

the same unix seconds as t

X-Xyra-Event

the event name, e.g. message.received

X-Xyra-Event-Id

unique per event, the same on every retry

Retries carry the same X-Xyra-Event-Id, so store it and ignore an id you have already processed.

Verifying the signature

Compute an HMAC-SHA256, keyed with the endpoint's signing secret, over <t>.<raw request body>, and compare it with v1. Reject deliveries whose t is more than 5 minutes old.

import crypto from "node:crypto";

// rawBody: the body exactly as received, not parsed
function verifyXyraWebhook(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((p) => p.split("="))
  );
  const t = Number(parts.t);
  // Reject anything older (or newer) than 5 minutes
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 ?? "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Delivery and retries

• • Your endpoint has 10 seconds to respond.
• • Any 2xx counts as delivered.
• • 410 Gone stops delivery and pauses the endpoint.
• • Any other 4xx is not retried.
• • A 5xx or a timeout is retried after 30 s, 1 min, 5 min, 30 min, 2 h, 6 h, 12 h and 24 h.

All 17 events