Verify Webhook Signatures

Every webhook request includes these headers:

Header	Value
`X-UnifyStay-Webhook-Id`	Stable event ID, such as `evt_...`.
`X-UnifyStay-Webhook-Timestamp`	Unix timestamp in seconds.
`X-UnifyStay-Webhook-Signature`	Comma-separated timestamp and signatures, such as `t=...,v1=...`.

The signature is the lowercase hexadecimal HMAC-SHA256 digest of:

{timestamp}.{exact_raw_request_body}

Verify the exact raw request bytes. Parsing JSON and serializing it again can change whitespace or key ordering and invalidate the signature.

Node.js Example

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

function verifyUnifystaysWebhook(
  rawBody: Buffer,
  timestampHeader: string,
  signatureHeader: string,
  secrets: string[],
) {
  const timestamp = Number(timestampHeader);
  if (!Number.isInteger(timestamp)) return false;

  // Reject requests more than five minutes away from the server clock.
  const age = Math.abs(Math.floor(Date.now() / 1000) - timestamp);
  if (age > 300) return false;

  const received = signatureHeader
    .split(",")
    .map((part) => part.trim().split("=", 2))
    .filter(
      ([version, value]) =>
        (version === "v1" || version === "v0") && /^[a-f0-9]{64}$/.test(value),
    )
    .map(([, value]) => Buffer.from(value, "hex"));

  const signedPayload = `${timestamp}.${rawBody.toString("utf8")}`;
  return secrets.some((secret) => {
    const expected = createHmac("sha256", secret)
      .update(signedPayload, "utf8")
      .digest();
    return received.some(
      (candidate) =>
        candidate.length === expected.length &&
        timingSafeEqual(candidate, expected),
    );
  });
}

Pass the current secret in secrets. During a planned rotation, temporarily pass both the new and previous secrets until the overlap expires.

Rotation Behavior

When you rotate a secret, the new secret is active immediately and the previous secret remains valid for 24 hours. During that overlap the signature header is:

t=1786177800,v1=<new-secret-signature>,v0=<previous-secret-signature>

Deploy verification for the new secret before removing the old one. After the previous_secret_valid_until timestamp, remove the previous secret from your receiver.

Safe Processing Order

Read the raw request body.
Validate the timestamp and signature.
Parse the JSON.
Deduplicate by the event id.
Persist or enqueue the event.
Return a 2xx response.

Never perform irreversible booking work before signature verification and deduplication succeed.

Get started

Build your integration

Operate

Node.js Example

Rotation Behavior

Safe Processing Order

​Node.js Example

​Rotation Behavior

​Safe Processing Order

Node.js Example

Rotation Behavior

Safe Processing Order