Verify webhook signatures

Verify before parsing

Your public HTTPS endpoint receives the three headers below:

Skinloop-Event-Id: evt_01K5F8N7Y4A2BCDEFGHJKMNPQR
Skinloop-Timestamp: 1789733100
Skinloop-Signature: v1=<64 lowercase hexadecimal characters>

Use the endpoint signing secret to compute HMAC-SHA256 over:

<eventId>.<timestamp>.<exact UTF-8 request bytes>

Skinloop-Timestamp is the current Unix timestamp in seconds, encoded as a decimal string. Compare the lowercase hexadecimal digest with Skinloop-Signature: v1=... using a constant-time comparison:

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

function validSignature(rawBody: Buffer, eventId: string, timestamp: string,
  signature: string, secret: string) {
  const message = Buffer.concat([
    Buffer.from(eventId, "utf8"),
    Buffer.from(".", "utf8"),
    Buffer.from(timestamp, "utf8"),
    Buffer.from(".", "utf8"),
    rawBody
  ]);
  const expected = createHmac("sha256", secret).update(message).digest("hex");
  const received = signature.startsWith("v1=") ? signature.slice(3) : "";
  return received.length === expected.length &&
    timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}

Use the timestamp to enforce a freshness window configured by your receiver. Reject malformed headers, stale timestamps, unknown secrets, and altered bodies. Read the request body as raw bytes first; never parse and reserialize it before verification. Store the event ID only after authentication. After verification, require Skinloop-Event-Id to equal the body id. See the complete webhook requests for all headers and body fields.

Complete Node and Express receiver

Install Express and your PostgreSQL client, then register this route before any global express.json() middleware. The route uses express.raw() because parsing and reserializing JSON changes the signed bytes.

View the complete Node and Express receiver

import { createHash, createHmac, timingSafeEqual } from "node:crypto";
import express from "express";
import { Pool, PoolClient } from "pg";
import { recordEventAndEnqueue } from "./orders.js";

const app = express();
const db = new Pool({ connectionString: process.env.DATABASE_URL });
const MAX_CLOCK_SKEW_SECONDS = 5 * 60;
const MAX_BODY_BYTES = "256kb";

function requiredHeader(
  req: express.Request,
  name: "skinloop-event-id" | "skinloop-timestamp" | "skinloop-signature"
) {
  const value = req.headers[name];
  if (typeof value !== "string" || value.includes(",")) {
    throw new Error(`missing or repeated ${name}`);
  }
  return value;
}

function verifyTimestamp(timestamp: string) {
  if (!/^[0-9]{1,20}$/.test(timestamp)) throw new Error("invalid timestamp");
  const signedAt = Number(timestamp);
  const now = Math.floor(Date.now() / 1000);
  if (!Number.isSafeInteger(signedAt)) throw new Error("invalid timestamp");
  if (Math.abs(now - signedAt) > MAX_CLOCK_SKEW_SECONDS) {
    throw new Error("stale timestamp");
  }
}

function validSignature(
  rawBody: Buffer,
  eventId: string,
  timestamp: string,
  signature: string,
  secrets: string[]
) {
  const match = /^v1=([0-9a-f]{64})$/.exec(signature);
  if (!match) return false;
  const received = Buffer.from(match[1], "hex");
  const message = Buffer.concat([
    Buffer.from(`${eventId}.${timestamp}.`, "utf8"),
    rawBody
  ]);

  // Evaluate every configured secret rather than stopping after the first
  // match. This supports a short, controlled rotation overlap.
  let valid = false;
  for (const secret of secrets) {
    const expected = createHmac("sha256", secret).update(message).digest();
    valid = timingSafeEqual(received, expected) || valid;
  }
  return valid;
}

type SkinloopEvent = {
  version: "1";
  id: string;
  type: string;
  createdAt: string;
  data: {
    externalPaymentId: string;
    merchantOrderId?: string;
    game: "cs2" | "rust";
    currency: "USD";
    amount: string;
    status: string;
    reservationRequired: boolean;
    fulfillmentAllowed: boolean;
    holdUntil?: string;
  };
};

async function storeEvent(
  client: PoolClient,
  event: SkinloopEvent,
  bodyDigest: string
) {
  const inserted = await client.query(
    `INSERT INTO skinloop_webhook_events
       (event_id, event_type, created_at, body_sha256, payload)
     VALUES ($1, $2, $3, $4, $5::jsonb)
     ON CONFLICT (event_id) DO NOTHING
     RETURNING event_id`,
    [event.id, event.type, event.createdAt, bodyDigest, JSON.stringify(event)]
  );
  if (inserted.rowCount === 1) return "inserted";

  const existing = await client.query(
    `SELECT body_sha256
       FROM skinloop_webhook_events
      WHERE event_id = $1
      FOR UPDATE`,
    [event.id]
  );
  if (existing.rows[0]?.body_sha256 !== bodyDigest) {
    throw new Error("event identity conflict");
  }
  return "duplicate";
}

app.post(
  "/webhooks/skinloop",
  express.raw({ type: "application/json", limit: MAX_BODY_BYTES }),
  async (req, res) => {
    if (!Buffer.isBuffer(req.body)) {
      return res.status(400).json({ error: "raw_body_required" });
    }

    let eventId: string;
    let timestamp: string;
    let signature: string;
    try {
      eventId = requiredHeader(req, "skinloop-event-id");
      timestamp = requiredHeader(req, "skinloop-timestamp");
      signature = requiredHeader(req, "skinloop-signature");
      if (!/^evt_[A-Za-z0-9]+$/.test(eventId)) {
        throw new Error("invalid event id");
      }
      verifyTimestamp(timestamp);
    } catch {
      return res.status(400).json({ error: "invalid_webhook_headers" });
    }

    const secrets = [
      process.env.SKINLOOP_WEBHOOK_SECRET_CURRENT,
      process.env.SKINLOOP_WEBHOOK_SECRET_PREVIOUS
    ].filter((value): value is string => Boolean(value));
    if (
      secrets.length === 0 ||
      !validSignature(req.body, eventId, timestamp, signature, secrets)
    ) {
      return res.status(401).json({ error: "invalid_signature" });
    }

    let event: SkinloopEvent;
    try {
      event = JSON.parse(req.body.toString("utf8")) as SkinloopEvent;
      if (
        event === null ||
        event.version !== "1" ||
        event.id !== eventId ||
        typeof event.type !== "string" ||
        typeof event.createdAt !== "string" ||
        event.data === null ||
        typeof event.data !== "object" ||
        typeof event.data.status !== "string"
      ) {
        throw new Error("invalid event");
      }
    } catch {
      return res.status(400).json({ error: "invalid_event" });
    }

    const bodyDigest = createHash("sha256").update(req.body).digest("hex");
    let client: PoolClient | undefined;
    try {
      client = await db.connect();
      await client.query("BEGIN");
      const result = await storeEvent(client, event, bodyDigest);

      if (result === "inserted") {
        // Record state and enqueue the same unique fulfillment job used by
        // status polling. Do not call an external fulfillment service here.
        await recordEventAndEnqueue(client, event);
      }

      await client.query("COMMIT");
      return res.status(200).json({
        received: true,
        duplicate: result === "duplicate"
      });
    } catch (error) {
      await client?.query("ROLLBACK").catch(() => undefined);
      if (
        error instanceof Error &&
        error.message === "event identity conflict"
      ) {
        return res.status(409).json({ error: "event_identity_conflict" });
      }
      return res.status(500).json({ error: "temporary_processing_failure" });
    } finally {
      client?.release();
    }
  }
);

// Register normal JSON parsing only after the webhook route.
app.use(express.json());

Create the corresponding event table:

CREATE TABLE skinloop_webhook_events (
  event_id TEXT PRIMARY KEY,
  event_type TEXT NOT NULL,
  created_at TIMESTAMPTZ NOT NULL,
  body_sha256 TEXT NOT NULL CHECK (body_sha256 ~ '^[0-9a-f]{64}$'),
  payload JSONB NOT NULL,
  received_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

recordEventAndEnqueue represents your local transactional status update and durable fulfillment-job insert from Safe fulfillment. Implement it with your own order schema. It must use the supplied database client so event storage and job creation commit together.

Timestamp policy

The receiver must reject a timestamp more than five minutes in the past or future relative to its own UTC clock. This limits replay exposure while allowing ordinary network delay and clock skew.

Synchronize production hosts with a reliable time service.
Perform the timestamp check before HMAC work and JSON parsing.
Do not use createdAt for signature freshness; use Skinloop-Timestamp.
Do not treat the freshness check as deduplication. An attacker can replay a valid request within five minutes, so the event-ID unique constraint remains required.

Endpoint secrets

Each webhook endpoint has its own signing secret beginning with whsec_. Skinloop displays the full secret only when the endpoint is created or its secret is rotated. Store it as a server-side secret:

SKINLOOP_WEBHOOK_SECRET_CURRENT=whsec_...
SKINLOOP_WEBHOOK_SECRET_PREVIOUS=whsec_...

Never put either value in browser code, source control, logs, support messages, or the event database. A secret belongs only to the endpoint for which it was issued; do not reuse it between staging and production.

Rotate without dropping events

The direct Rotate secret action replaces an endpoint’s secret immediately and returns the new value once. Because the new value cannot be deployed before it is created, use two endpoint records for a planned zero-downtime rotation:

Create a second webhook endpoint with the same HTTPS URL and event subscriptions. Securely capture its new secret.
Deploy the new secret as CURRENT and the old endpoint’s secret as PREVIOUS.
Trigger a webhook test for the new endpoint and confirm it verifies.
Revoke the old endpoint in Skinloop.
Keep the old secret as PREVIOUS for one hour to cover requests already in flight.
Remove PREVIOUS and test the remaining endpoint again.

While both endpoints are active, the same event can be delivered through each endpoint. The event-ID unique constraint makes that overlap safe. For an emergency response to suspected exposure, use Rotate secret immediately, update CURRENT as quickly as possible, and remove the compromised secret rather than keeping an overlap. A short rejection window is safer than accepting a known-compromised secret. The receiver checks both configured secrets during planned overlap. Do not keep old secrets indefinitely.

Response contract

Situation	Response	Skinloop behavior
Authenticated event committed	`200` with `{"received":true,"duplicate":false}`	Delivery accepted
Authenticated duplicate with matching bytes	`200` with `{"received":true,"duplicate":true}`	Delivery accepted; no repeated state change or fulfillment
Missing, repeated, malformed, stale, or future-dated headers	`400`	Delivery rejected
Signature does not verify with current or previous secret	`401`	Delivery rejected
Header event ID differs from body `id`, or body is malformed	`400`	Delivery rejected
Same authenticated event ID with different bytes	`409`	Conflict requires investigation
Temporary database or enqueue failure	`500`	Skinloop can retry

Return 2xx only after durable storage and any required fulfillment job commit. Do not return 2xx first and continue important work only in process memory. Next: test retries and accepted duplicates in Webhook retries and deduplication.

Getting started

Hosted checkout

Player balance deposits

Store integrations

Payments and payouts

Webhooks and reliability

Resources

API reference

Verify webhook signatures

Verify before parsing

Complete Node and Express receiver

Timestamp policy

Endpoint secrets

Rotate without dropping events

Response contract

​Verify before parsing

​Complete Node and Express receiver

​Timestamp policy

​Endpoint secrets

​Rotate without dropping events

​Response contract

Verify before parsing

Complete Node and Express receiver

Timestamp policy

Endpoint secrets

Rotate without dropping events

Response contract