Webhooks

curl "https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/webhooks" \
  -H "Authorization: Bearer zk_test_XXXXXXXX_…zk_live_XXXXXXXX_…" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://erp.example.com/zestt/webhooks",
    "events": ["order.created", "order.updated", "document.received"],
    "description": "Priority ERP: orders and documents"
  }'

curl -X POST "https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/webhooks/wh_01J9KR2B7N/test" \
  -H "Authorization: Bearer zk_test_XXXXXXXX_…zk_live_XXXXXXXX_…"

Content-Type: application/json
Zestt-Signature: t=1789103702,v1=…

// npm install express
const crypto = require("node:crypto");
const express = require("express");

const SECRET = process.env.ZESTT_WEBHOOK_SECRET;
if (!SECRET) throw new Error("ZESTT_WEBHOOK_SECRET is not set");
const TOLERANCE_SECONDS = 300;

function verifyZesttSignature(rawBody, header, secret) {
  if (typeof header !== "string") return false;

  let timestamp = null;
  const signatures = [];
  for (const part of header.split(",")) {
    const i = part.indexOf("=");
    if (i === -1) continue;
    const key = part.slice(0, i).trim();
    const value = part.slice(i + 1).trim();
    if (key === "t") timestamp = value;
    else if (key === "v1") signatures.push(value);
  }
  if (!timestamp || !/^\d+$/.test(timestamp) || signatures.length === 0) return false;

  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
  if (age > TOLERANCE_SECONDS) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(timestamp + ".")
    .update(rawBody)
    .digest();

  return signatures.some(
    (sig) => /^[0-9a-f]{64}$/i.test(sig) && crypto.timingSafeEqual(expected, Buffer.from(sig, "hex"))
  );
}

const app = express();

// express.raw() keeps the body as a Buffer, byte for byte.
// Do not put express.json() in front of this route.
app.post("/zestt/webhooks", express.raw({ type: "*/*" }), (req, res) => {
  const header = req.get("Zestt-Signature");
  if (!Buffer.isBuffer(req.body) || !verifyZesttSignature(req.body, header, SECRET)) {
    return res.status(400).send("invalid signature");
  }

  const event = JSON.parse(req.body.toString("utf8"));
  res.status(200).send("ok");

  // Respond first, then process. In production, write the event to a queue or a table.
  setImmediate(() => handleEvent(event));
});

function handleEvent(event) {
  console.log(event.id, event.type, event.data.id);
}

app.listen(3000);

# pip install flask
import hashlib
import hmac
import json
import os
import re
import threading
import time

from flask import Flask, request

SECRET = os.environ["ZESTT_WEBHOOK_SECRET"].encode("utf-8")
TOLERANCE_SECONDS = 300

app = Flask(__name__)


def verify_zestt_signature(raw_body, header, secret):
    if not header:
        return False

    timestamp = None
    signatures = []
    for part in header.split(","):
        key, sep, value = part.partition("=")
        if not sep:
            continue
        key, value = key.strip(), value.strip()
        if key == "t":
            timestamp = value
        elif key == "v1":
            signatures.append(value)
    if timestamp is None or not re.fullmatch("[0-9]+", timestamp) or not signatures:
        return False

    if abs(int(time.time()) - int(timestamp)) > TOLERANCE_SECONDS:
        return False

    signed_payload = timestamp.encode("ascii") + b"." + raw_body
    expected = hmac.new(secret, signed_payload, hashlib.sha256).hexdigest()
    return any(
        hmac.compare_digest(expected.encode("ascii"), sig.lower().encode("utf-8"))
        for sig in signatures
    )


@app.route("/zestt/webhooks", methods=["POST"])
def zestt_webhooks():
    # get_data() returns the body exactly as sent. Do not use request.json here.
    raw_body = request.get_data()
    header = request.headers.get("Zestt-Signature")
    if not verify_zestt_signature(raw_body, header, SECRET):
        return "invalid signature", 400

    event = json.loads(raw_body)

    # Respond first, then process. In production, write the event to a queue or a table.
    threading.Thread(target=handle_event, args=(event,), daemon=True).start()
    return "ok", 200


def handle_event(event):
    print(event["id"], event["type"], event["data"]["id"])


if __name__ == "__main__":
    app.run(port=3000)

// dotnet new web, then replace Program.cs
using System.Globalization;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

var secret = Encoding.UTF8.GetBytes(
    Environment.GetEnvironmentVariable("ZESTT_WEBHOOK_SECRET")
    ?? throw new InvalidOperationException("ZESTT_WEBHOOK_SECRET is not set"));

app.MapPost("/zestt/webhooks", async (HttpRequest request) =>
{
    // Read the raw bytes. Do not bind the body to a model before verifying.
    using var buffer = new MemoryStream();
    await request.Body.CopyToAsync(buffer);
    var rawBody = buffer.ToArray();

    var header = request.Headers["Zestt-Signature"].ToString();
    if (!VerifyZesttSignature(rawBody, header, secret))
        return Results.BadRequest("invalid signature");

    using var json = JsonDocument.Parse(rawBody);
    var id = json.RootElement.GetProperty("id").GetString();
    var type = json.RootElement.GetProperty("type").GetString();

    // Respond first, then process. In production, write the event to a queue or a table.
    app.Logger.LogInformation("Zestt event {Id} {Type}", id, type);
    return Results.Ok();
});

app.Run();

static bool VerifyZesttSignature(byte[] rawBody, string header, byte[] secret)
{
    const long toleranceSeconds = 300;

    string? timestamp = null;
    var signatures = new List<string>();
    foreach (var part in header.Split(','))
    {
        var i = part.IndexOf('=');
        if (i < 0) continue;
        var key = part[..i].Trim();
        var value = part[(i + 1)..].Trim();
        if (key == "t") timestamp = value;
        else if (key == "v1") signatures.Add(value);
    }
    if (timestamp is null || signatures.Count == 0 ||
        !long.TryParse(timestamp, NumberStyles.None, CultureInfo.InvariantCulture, out var t))
        return false;

    if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - t) > toleranceSeconds)
        return false;

    var prefix = Encoding.ASCII.GetBytes(timestamp + ".");
    var signedPayload = new byte[prefix.Length + rawBody.Length];
    prefix.CopyTo(signedPayload, 0);
    rawBody.CopyTo(signedPayload, prefix.Length);
    var expected = HMACSHA256.HashData(secret, signedPayload);

    foreach (var signature in signatures)
    {
        if (signature.Length != 64) continue;
        byte[] received;
        try { received = Convert.FromHexString(signature); }
        catch (FormatException) { continue; }
        if (CryptographicOperations.FixedTimeEquals(expected, received)) return true;
    }
    return false;
}

curl -X PATCH "https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/webhooks/wh_01J9KR2B7N" \
  -H "Authorization: Bearer zk_test_XXXXXXXX_…zk_live_XXXXXXXX_…" \
  -H "Content-Type: application/json" \
  -d '{ "status": "active" }'