Webhooks

curl https://api.senderz.app/api/v1/public/webhooks \
  -H "X-Sender-Tenant: acme-il" \
  -H "X-API-Key: your-api-key"

{
  "success": true,
  "data": [
    {
      "id": "b7c81f04-3a2e-4d19-9c65-1f8ad30e5b72",
      "name": "Order events to Make",
      "url": "https://hook.eu2.make.com/8k3jd9smq1x4",
      "events": ["order.completed", "cart.abandoned"],
      "active": true,
      "createdAt": "2026-02-11T09:14:22.318Z"
    },
    {
      "id": "2d4a9e37-6b10-4c88-a5f3-0e7b62c1d945",
      "name": null,
      "url": "https://ops.acme.co.il/senderz/hooks",
      "events": ["*"],
      "active": true,
      "createdAt": "2026-01-28T16:02:07.904Z"
    }
  ]
}

curl -X POST https://api.senderz.app/api/v1/public/webhooks \
  -H "X-Sender-Tenant: acme-il" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order events to Make",
    "url": "https://hook.eu2.make.com/8k3jd9smq1x4",
    "events": ["order.completed", "cart.abandoned"]
  }'

const res = await fetch("https://api.senderz.app/api/v1/public/webhooks", {
  method: "POST",
  headers: {
    "X-Sender-Tenant": "acme-il",
    "X-API-Key": process.env.SENDERZ_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Order events to Make",
    url: "https://hook.eu2.make.com/8k3jd9smq1x4",
    events: ["order.completed", "cart.abandoned"],
  }),
});

const { data } = await res.json();
// Persist data.signingSecret now. It is never returned again.

import os, requests

res = requests.post(
    "https://api.senderz.app/api/v1/public/webhooks",
    headers={
        "X-Sender-Tenant": "acme-il",
        "X-API-Key": os.environ["SENDERZ_API_KEY"],
    },
    json={
        "name": "Order events to Make",
        "url": "https://hook.eu2.make.com/8k3jd9smq1x4",
        "events": ["order.completed", "cart.abandoned"],
    },
)
data = res.json()["data"]
# Persist data["signingSecret"] now. It is never returned again.

{
  "success": true,
  "data": {
    "id": "b7c81f04-3a2e-4d19-9c65-1f8ad30e5b72",
    "name": "Order events to Make",
    "url": "https://hook.eu2.make.com/8k3jd9smq1x4",
    "events": ["order.completed", "cart.abandoned"],
    "active": true,
    "createdAt": "2026-02-11T09:14:22.318Z",
    "signingSecret": "3f8a1c7d9e0b4a62f15d8c37b2e64a90d5f1c8b73a2e69d04c1f7b8a35e29d6c"
  }
}

curl "https://api.senderz.app/api/v1/public/events?limit=3&offset=28" \
  -H "X-Sender-Tenant: acme-il" \
  -H "X-API-Key: your-api-key"

{
  "success": true,
  "data": {
    "items": [
      { "value": "loyalty.referral", "label": "loyalty.referral", "kind": "system" },
      {
        "value": "warranty_registered",
        "label": "Warranty registered",
        "kind": "custom_event",
        "properties": ["sku", "purchasedAt"]
      },
      {
        "value": "showroom_visit_booked",
        "label": "Showroom visit booked",
        "kind": "custom_event",
        "properties": ["branch"]
      }
    ],
    "limit": 3,
    "offset": 28,
    "total": 31,
    "has_more": false,
    "next_cursor": null
  }
}

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.SENDERZ_WEBHOOK_SECRET;

function isValid(rawBody, header) {
  if (!header) return false;
  const expected = Buffer.from(
    "sha256=" + crypto.createHmac("sha256", SECRET).update(rawBody).digest("hex"),
  );
  const received = Buffer.from(header);
  return (
    expected.length === received.length &&
    crypto.timingSafeEqual(expected, received)
  );
}

// express.raw keeps the exact bytes. express.json would discard them.
app.post("/senderz/hooks", express.raw({ type: "application/json" }), (req, res) => {
  if (!isValid(req.body, req.get("X-Sender-Signature"))) {
    return res.sendStatus(401);
  }

  const { event, data, deliveryId } = JSON.parse(req.body.toString("utf8"));
  // Deduplicate on deliveryId, then acknowledge fast and process asynchronously.
  res.sendStatus(200);
});

import hashlib
import hmac
import json
import os

from flask import Flask, request

app = Flask(__name__)
SECRET = os.environ["SENDERZ_WEBHOOK_SECRET"].encode()


def is_valid(raw: bytes, header: str | None) -> bool:
    if not header:
        return False
    digest = hmac.new(SECRET, raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={digest}", header)


@app.post("/senderz/hooks")
def hooks():
    raw = request.get_data()  # raw bytes, before any JSON parsing
    if not is_valid(raw, request.headers.get("X-Sender-Signature")):
        return "", 401

    payload = json.loads(raw)
    # Deduplicate on payload["deliveryId"], then acknowledge fast.
    return "", 200

<?php
$secret = getenv('SENDERZ_WEBHOOK_SECRET');
$raw = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_SENDER_SIGNATURE'] ?? '';

$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);

if (!hash_equals($expected, $header)) {
    http_response_code(401);
    exit;
}

$payload = json_decode($raw, true);
// Deduplicate on $payload['deliveryId'], then acknowledge fast.
http_response_code(200);

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"io"
	"net/http"
	"os"
)

var secret = []byte(os.Getenv("SENDERZ_WEBHOOK_SECRET"))

func valid(raw []byte, header string) bool {
	mac := hmac.New(sha256.New, secret)
	mac.Write(raw)
	expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
	return hmac.Equal([]byte(expected), []byte(header))
}

func hooks(w http.ResponseWriter, r *http.Request) {
	raw, err := io.ReadAll(r.Body)
	if err != nil || !valid(raw, r.Header.Get("X-Sender-Signature")) {
		w.WriteHeader(http.StatusUnauthorized)
		return
	}
	// Deduplicate on deliveryId, then acknowledge fast.
	w.WriteHeader(http.StatusOK)
}