Webhooks

{
  "id": "PUTWALL-A:WAVE-0815:mvj9mso0-3:12",
  "type": "order.completed",
  "at": "2026-10-22T09:14:03.120Z",
  "layoutId": "PUTWALL-A",
  "waveId": "WAVE-0815",
  "data": {
    "orderId": "ORD-1001",
    "bins": [{ "id": "A-01-01", "wallId": "A" }],
    "short": false,
    "unitsPut": 3,
    "unitsTotal": 3
  }
}

curl -s "$SLOTTING_URL/api/webhooks/dead-letters"

/**
 * True when `header` (the x-slotting-signature header, `t=<unix seconds>,v1=<hex>`) is the HMAC-SHA256 of
 * "<t>.<raw body>" with your secret, and `t` is at most `toleranceSec` seconds away from now (against replays).
 * `rawBody` must be the exact bytes received: verify before parsing the JSON.
 */
export function verifySignature(secret: string, header: string | undefined, rawBody: Buffer, toleranceSec = 300): boolean {
    let t = '';
    const signatures: string[] = [];
    for (const part of (header ?? '').split(',')) {
        const eq = part.indexOf('=');
        const key = part.slice(0, eq).trim();
        const value = part.slice(eq + 1).trim();
        if (key === 't') {
            t = value;
        }
        else if (key === 'v1' && /^[0-9a-f]{64}$/.test(value)) {
            signatures.push(value);
        }
    }
    if (!/^\d{1,12}$/.test(t) || Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) {
        return false;
    }
    const expected = createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest();
    return signatures.some(sig => timingSafeEqual(expected, Buffer.from(sig, 'hex')));
}

interface SlottingEvent {
    id: string;
    type: string;
    at: string;
    layoutId: string;
    waveId: string;
    data: Record<string, unknown>;
}

const secret = process.env.SLOTTING_WEBHOOK_SECRET ?? '';
const port = Number(process.env.WEBHOOK_PORT ?? 9101);
// Events can arrive more than once: remember the ids you processed. In production, a unique key in your database.
const processed = new Set<string>();

function handle(event: SlottingEvent): void {
    console.log(`verified ${event.type} ${event.id}`);
}

createServer((req, res) => {
    const chunks: Buffer[] = [];
    let size = 0;
    req.on('data', (chunk: Buffer) => {
        size += chunk.length;
        if (size > 1_000_000) {
            res.writeHead(413).end();
            req.destroy();
            return;
        }
        chunks.push(chunk);
    });
    req.on('end', () => {
        const raw = Buffer.concat(chunks);
        const header = req.headers['x-slotting-signature'];
        if (req.method !== 'POST' || !verifySignature(secret, typeof header === 'string' ? header : undefined, raw)) {
            res.writeHead(401).end();
            return;
        }
        const event = JSON.parse(raw.toString('utf8')) as SlottingEvent;
        if (!processed.has(event.id)) {
            processed.add(event.id);
            handle(event);
        }
        // Answer 2xx quickly (within SLOTTING_WEBHOOK_TIMEOUT_MS), also for a duplicate; do slow work afterwards.
        res.writeHead(204).end();
    });
}).listen(port, '127.0.0.1');

/**
 * True when {@code header} (the x-slotting-signature header, {@code t=<unix seconds>,v1=<hex>}) is the HMAC-SHA256 of
 * "<t>.<raw body>" with your secret, and {@code t} is at most {@code toleranceSec} seconds away from now (against replays).
 * {@code rawBody} must be the exact bytes received: verify before parsing the JSON.
 */
public static boolean verifySignature(String secret, String header, byte[] rawBody, long toleranceSec) {
    if (header == null) {
        return false;
    }
    String t = "";
    List<String> signatures = new ArrayList<>();
    for (String part : header.split(",")) {
        int eq = part.indexOf('=');
        if (eq <= 0) {
            continue;
        }
        String key = part.substring(0, eq).trim();
        String value = part.substring(eq + 1).trim();
        if (key.equals("t")) {
            t = value;
        }
        else if (key.equals("v1") && HEX_64.matcher(value).matches()) {
            signatures.add(value);
        }
    }
    if (!DIGITS.matcher(t).matches() || Math.abs(System.currentTimeMillis() / 1000 - Long.parseLong(t)) > toleranceSec) {
        return false;
    }
    byte[] expected;
    try {
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        mac.update((t + ".").getBytes(StandardCharsets.UTF_8));
        expected = mac.doFinal(rawBody);
    }
    catch (NoSuchAlgorithmException | InvalidKeyException e) {
        throw new IllegalStateException("HmacSHA256 is not available", e);
    }
    for (String signature : signatures) {
        // MessageDigest.isEqual compares in constant time.
        if (MessageDigest.isEqual(expected, HexFormat.of().parseHex(signature))) {
            return true;
        }
    }
    return false;
}

// Events can arrive more than once: remember the ids you processed. In production, a unique key in your database.
private static final Set<String> PROCESSED = ConcurrentHashMap.newKeySet();
private static final Pattern EVENT_ID = Pattern.compile("^\\{\"id\":\"((?:[^\"\\\\]|\\\\.)*)\",\"type\":\"([a-z.]+)\"");

public static void main(String[] args) throws IOException {
    String secret = System.getenv().getOrDefault("SLOTTING_WEBHOOK_SECRET", "");
    int port = Integer.parseInt(System.getenv().getOrDefault("WEBHOOK_PORT", "9102"));
    HttpServer server = HttpServer.create(new InetSocketAddress("127.0.0.1", port), 0);
    server.createContext("/", exchange -> {
        try (exchange) {
            byte[] raw = readBody(exchange, 1_000_000);
            String header = exchange.getRequestHeaders().getFirst("X-Slotting-Signature");
            if (raw == null || !exchange.getRequestMethod().equals("POST") || !verifySignature(secret, header, raw, 300)) {
                exchange.sendResponseHeaders(401, -1);
                return;
            }
            // Parse the body with your JSON library (Jackson, Gson); this example only reads id and type, which come first.
            Matcher m = EVENT_ID.matcher(new String(raw, StandardCharsets.UTF_8));
            if (m.find() && PROCESSED.add(m.group(1))) {
                System.out.println("verified " + m.group(2) + " " + m.group(1));
            }
            // Answer 2xx quickly (within SLOTTING_WEBHOOK_TIMEOUT_MS), also for a duplicate; do slow work afterwards.
            exchange.sendResponseHeaders(204, -1);
        }
    });
    server.start();
}

def verify_signature(secret, header, raw_body, tolerance_sec=300):
    """True when header (the x-slotting-signature header, "t=<unix seconds>,v1=<hex>") is the HMAC-SHA256 of
    "<t>.<raw body>" with your secret, and t is at most tolerance_sec seconds away from now (against replays).
    raw_body must be the exact bytes received (bytes, not str): verify before parsing the JSON."""
    t = ""
    signatures = []
    for part in (header or "").split(","):
        key, _, value = part.partition("=")
        key, value = key.strip(), value.strip()
        if key == "t":
            t = value
        elif key == "v1" and re.fullmatch(r"[0-9a-f]{64}", value):
            signatures.append(value)
    if not re.fullmatch(r"\d{1,12}", t) or abs(time.time() - int(t)) > tolerance_sec:
        return False
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, sig) for sig in signatures)

SECRET = os.environ.get("SLOTTING_WEBHOOK_SECRET", "")
# Events can arrive more than once: remember the ids you processed. In production, a unique key in your database.
processed = set()


def handle(event):
    print(f"verified {event['type']} {event['id']}", flush=True)


class Receiver(BaseHTTPRequestHandler):
    def do_POST(self):
        length = int(self.headers.get("Content-Length") or 0)
        if length > 1_000_000:
            self.send_response(413)
            self.end_headers()
            return
        raw = self.rfile.read(length)
        if not verify_signature(SECRET, self.headers.get("X-Slotting-Signature"), raw):
            self.send_response(401)
            self.end_headers()
            return
        event = json.loads(raw)
        if event["id"] not in processed:
            processed.add(event["id"])
            handle(event)
        # Answer 2xx quickly (within SLOTTING_WEBHOOK_TIMEOUT_MS), also for a duplicate; do slow work afterwards.
        self.send_response(204)
        self.end_headers()

    def log_message(self, format, *args):  # keep the output to the events
        pass


if __name__ == "__main__":
    ThreadingHTTPServer(("127.0.0.1", int(os.environ.get("WEBHOOK_PORT", "9103"))), Receiver).serve_forever()

/// <summary>
/// True when <paramref name="header"/> (the x-slotting-signature header, <c>t=&lt;unix seconds&gt;,v1=&lt;hex&gt;</c>) is the
/// HMAC-SHA256 of "&lt;t&gt;.&lt;raw body&gt;" with your secret, and t is at most <paramref name="toleranceSec"/> seconds
/// away from now (against replays). <paramref name="rawBody"/> must be the exact bytes received: verify before parsing.
/// </summary>
public static bool VerifySignature(string secret, string? header, byte[] rawBody, long toleranceSec = 300)
{
    var t = "";
    var signatures = new List<string>();
    foreach (var part in (header ?? "").Split(','))
    {
        var eq = part.IndexOf('=');
        if (eq <= 0)
        {
            continue;
        }
        var key = part[..eq].Trim();
        var value = part[(eq + 1)..].Trim();
        if (key == "t")
        {
            t = value;
        }
        else if (key == "v1" && value.Length == 64 && value.All(Uri.IsHexDigit))
        {
            signatures.Add(value);
        }
    }
    if (t.Length is 0 or > 12 || !t.All(char.IsAsciiDigit) || Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - long.Parse(t)) > toleranceSec)
    {
        return false;
    }
    var signed = Encoding.UTF8.GetBytes(t + ".").Concat(rawBody).ToArray();
    var expected = HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), signed);
    // FixedTimeEquals compares in constant time.
    return signatures.Any(sig => CryptographicOperations.FixedTimeEquals(expected, Convert.FromHexString(sig)));
}

var secret = Environment.GetEnvironmentVariable("SLOTTING_WEBHOOK_SECRET") ?? "";
// Events can arrive more than once: remember the ids you processed. In production, a unique key in your database.
var processed = new ConcurrentDictionary<string, bool>();

app.MapPost("/", async (HttpRequest request) =>
{
    if (request.ContentLength is null or > 1_000_000)
    {
        return Results.StatusCode(413);
    }
    using var buffer = new MemoryStream();
    await request.Body.CopyToAsync(buffer);
    var raw = buffer.ToArray();
    if (!SlottingWebhooks.VerifySignature(secret, request.Headers["X-Slotting-Signature"].ToString(), raw))
    {
        return Results.Unauthorized();
    }
    var slottingEvent = JsonNode.Parse(raw)!;
    var id = (string)slottingEvent["id"]!;
    if (processed.TryAdd(id, true))
    {
        Console.WriteLine($"verified {slottingEvent["type"]} {id}");
    }
    // Answer 2xx quickly (within SLOTTING_WEBHOOK_TIMEOUT_MS), also for a duplicate; do slow work afterwards.
    return Results.NoContent();
});