MarginTide — Guía de conectores de webhook

Códigos de motivo

Códigos de motivo

workspace_id identifica a cuál de sus espacios de trabajo pertenece la solicitud — es obligatorio cuando un mismo receptor atiende a varios espacios de trabajo o tiendas; puede ignorarlo sin problema si su receptor solo atiende a un espacio de trabajo.

Verificar la firma

Vuelva a calcular el resumen HMAC-SHA256 sobre la marca de tiempo y el cuerpo bruto de la solicitud usando su secreto de firma, compárelo con el encabezado usando una comparación de tiempo constante, y rechace la solicitud si la marca de tiempo queda fuera de la ventana de repetición.

Ventana de repetición: 300s

Compare siempre los resúmenes con una función de tiempo constante — una comparación simple de cadenas o de bytes revela información de temporización que un atacante puede usar para falsificar una firma válida un byte a la vez.

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

Receptor de muestra

Un receptor de Node.js en un solo archivo, sin dependencias, que verifica ambos esquemas de firma, responde a las solicitudes de escritura por webhook para un mapa de SKU fijo, registra los eventos salientes, maneja ambas sondas de prueba y rechaza firmas incorrectas o vencidas. Cópielo como punto de partida.

#!/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);
});