MarginTide — Webhook connectors guide

Reason codes

Reason codes

workspace_id identifies which of your workspaces the request belongs to — required when one receiver serves multiple workspaces or storefronts; ignore it safely if your receiver only ever serves one.

Verifying the signature

Recompute the HMAC-SHA256 digest over the timestamp and raw request body using your signing secret, compare it to the header using a constant-time comparison, and reject the request if the timestamp falls outside the replay window.

Replay window: 300s

Always compare digests with a constant-time function — a plain string or byte-array equality check leaks timing information an attacker can use to forge a valid signature one byte at a time.

const crypto = require("node:crypto");

function computeSignature(secret, t, rawBody) {
  const basestring = "v1:" + t + ":" + rawBody;
  return crypto.createHmac("sha256", secret).update(basestring).digest("hex");
}

function verifySignature(secret, header, rawBody, nowSeconds) {
  const match = /^t=(\d+),v1=([0-9a-f]+)$/.exec(header || "");
  if (!match) return false;
  const t = Number(match[1]);
  const v1 = match[2];
  const now = nowSeconds != null ? nowSeconds : Math.floor(Date.now() / 1000);
  if (Math.abs(now - t) > 300) return false;
  const expected = computeSignature(secret, t, rawBody);
  const expectedBuf = Buffer.from(expected, "utf8");
  const actualBuf = Buffer.from(v1, "utf8");
  if (expectedBuf.length !== actualBuf.length) return false;
  return crypto.timingSafeEqual(expectedBuf, actualBuf);
}

import hashlib
import hmac
import re
import time


def compute_signature(secret, t, raw_body):
    basestring = f"v1:{t}:{raw_body}"
    return hmac.new(secret.encode("utf-8"), basestring.encode("utf-8"), hashlib.sha256).hexdigest()


def verify_signature(secret, header, raw_body, now_seconds=None):
    match = re.match(r"^t=(\d+),v1=([0-9a-f]+)$", header or "")
    if not match:
        return False
    t = int(match.group(1))
    v1 = match.group(2)
    now = now_seconds if now_seconds is not None else int(time.time())
    if abs(now - t) > 300:
        return False
    expected = compute_signature(secret, t, raw_body)
    return hmac.compare_digest(expected, v1)

secret: whsec_test0000000000000000000000000001
t:      1735689600
body:   {"workspace_id":"11111111-1111-4111-8111-111111111111","sku":"__agnotiq_test__","currency":"USD"}
sig:    t=1735689600,v1=b99f548315a20e8ae7282b0966e3f276406611fcdee790b8863398416d35c9fb

secret: whsec_test0000000000000000000000000002
t:      1735689600
body:   {"version":"1.0.0","id":"22222222-2222-4222-8222-222222222222","type":"ping","created_at":"2025-01-01T00:00:00.000Z","data":{"message":"ping","webhook_id":"33333333-3333-4333-8333-333333333333","workspace_id":"11111111-1111-4111-8111-111111111111"}}
sig:    t=1735689600,v1=4cde38ded48071a9a44cc5fc5750a3c9d404ddb4f85fb87812aaae02c46272ab

Sample receiver

A single-file, zero-dependency Node.js receiver that verifies both signature schemes, answers write-back requests for a hardcoded SKU map, logs outbound events, handles both test probes, and rejects bad or expired signatures. Copy it as a starting point.

#!/usr/bin/env node
// Agnotiq sample webhook receiver — zero dependencies, node: builtins only.
// Verifies both signature schemes (091 write-back, 066 outbound events),
// answers commerce.resolve / commerce.price.set for a demo SKU catalog,
// logs 066 events, and handles both test probes.
//
// Run:  WRITEBACK_SECRET=whsec_... EVENTS_SECRET=whsec_... node receiver.js
// Port: set PORT (0 = ephemeral, the OS picks a free port).

"use strict";

const http = require("node:http");
const crypto = require("node:crypto");

const WRITEBACK_SECRET = process.env.WRITEBACK_SECRET || "";
const EVENTS_SECRET = process.env.EVENTS_SECRET || "";
const REPLAY_WINDOW_SECONDS = 300;
const SIGNATURE_VERSION = "v1";
const TEST_SKU = "__agnotiq_test__";

// Hardcoded demo catalog — replace with your own product lookup.
const SKU_CATALOG = {
  "DEMO-SKU-1": { externalProductRef: "demo-ref-1", livePrice: "19.99" },
};

function computeSignature(secret, t, rawBody) {
  const basestring = SIGNATURE_VERSION + ":" + t + ":" + rawBody;
  return crypto.createHmac("sha256", secret).update(basestring).digest("hex");
}

function verifySignature(secret, header, rawBody, nowSeconds) {
  if (!header) return false;
  const match = /^t=(\d+),v1=([0-9a-f]+)$/.exec(header);
  if (!match) return false;
  const t = Number(match[1]);
  const v1 = match[2];
  const now = nowSeconds != null ? nowSeconds : Math.floor(Date.now() / 1000);
  if (Math.abs(now - t) > REPLAY_WINDOW_SECONDS) return false;
  const expected = computeSignature(secret, t, rawBody);
  const expectedBuf = Buffer.from(expected, "utf8");
  const actualBuf = Buffer.from(v1, "utf8");
  if (expectedBuf.length !== actualBuf.length) return false;
  return crypto.timingSafeEqual(expectedBuf, actualBuf);
}

const server = http.createServer((req, res) => {
  const chunks = [];
  req.on("data", (chunk) => chunks.push(chunk));
  req.on("end", () => {
    const rawBody = Buffer.concat(chunks).toString("utf8");
    const eventType = req.headers["x-agnotiq-event"];
    const signatureHeader = req.headers["x-agnotiq-signature"];

    function respond(status, body) {
      res.writeHead(status, { "Content-Type": "application/json" });
      res.end(JSON.stringify(body));
    }

    if (eventType === "commerce.resolve" || eventType === "commerce.price.set") {
      if (!verifySignature(WRITEBACK_SECRET, signatureHeader, rawBody)) {
        respond(401, { ok: false, reason: "auth_failed", message: "bad or expired signature" });
        return;
      }
      let payload;
      try {
        payload = JSON.parse(rawBody);
      } catch (err) {
        respond(400, { ok: false, reason: "auth_failed", message: "invalid json" });
        return;
      }
      if (eventType === "commerce.resolve") {
        if (payload.sku === TEST_SKU) {
          respond(200, { ok: false, reason: "sku_not_found", message: "test probe" });
          return;
        }
        const entry = SKU_CATALOG[payload.sku];
        if (!entry) {
          respond(200, { ok: false, reason: "sku_not_found" });
          return;
        }
        respond(200, { ok: true, externalProductRef: entry.externalProductRef, livePrice: entry.livePrice });
        return;
      }
      // commerce.price.set — apply and echo back the price.
      respond(200, { ok: true, appliedPrice: payload.price });
      return;
    }

    // Outbound events (066): run.completed / alert.critical /
    // recommendation.accepted / recommendation.applied / ping.
    if (!verifySignature(EVENTS_SECRET, signatureHeader, rawBody)) {
      respond(401, { ok: false, message: "bad or expired signature" });
      return;
    }
    let envelope;
    try {
      envelope = JSON.parse(rawBody);
    } catch (err) {
      respond(400, { ok: false, message: "invalid json" });
      return;
    }
    console.log("[sample-receiver] event:", envelope.type, envelope.id);
    respond(200, { ok: true });
  });
});

const requestedPort = process.env.PORT ? Number(process.env.PORT) : 0;
server.listen(requestedPort, "127.0.0.1", () => {
  const address = server.address();
  const actualPort = address && typeof address === "object" ? address.port : requestedPort;
  console.log("listening " + actualPort);
});