Back to the docs
Developers
Business

Webhooks

Mujaz sends your server a signed request for each event you care about: a new subscriber, a confirmation, an unsubscribe, a bounce, an import, or an issue sent.

Setup

  1. 1. In Settings → API → Webhooks add an https:// address on port 443 and pick the events you want. Up to 5 addresses per account (Business plan).
  2. 2. Copy the signing secret (whsec_…) at once: it is shown in full only once. Keep it in an environment variable on your server.
  3. 3. Press “Send test”: a ping event arrives and you see the HTTP code your server returned and how long it took.

We refuse private or local network addresses, Mujaz's own addresses, and ports other than 443. The address is checked again on every connection.

Events

subscriber.created
A new subscriber from anywhere: the API, the dashboard, or a sign-up form. Never for someone already here.
subscriber.confirmed
A subscriber confirmed their email (pending → active).
subscriber.unsubscribed
A real unsubscribe, with reason and via: link, one_click, report, dashboard or api.
subscriber.bounced
A subscriber's email bounced, with bounceType (permanent or transient). Once per person.
subscriber.complained
A subscriber marked an email as spam. Once per person.
subscribers.imported
An import finished (dashboard or bulk add): one event with the counts, never one per row.
newsletter.sent
An issue finished sending. Once per issue.
ping
The “Send test” button only, to that one address. data is empty: {}.

What we send

http
POST /hooks/mujaz HTTP/1.1
Content-Type: application/json
User-Agent: Mujaz-Webhooks/1.0
Mujaz-Event-Id: evt_6740c1f2a9b8e4d3c2b1a0f9
Mujaz-Event-Type: subscriber.created
Mujaz-Signature: t=1763460000,v1=5f2c…
json
{
  "id": "evt_6740c1f2a9b8e4d3c2b1a0f9",
  "type": "subscriber.created",
  "createdAt": "2026-11-18T10:00:00.000Z",
  "apiVersion": "v1",
  "workspace": { "id": "6720f0a1b2c3d4e5f6a7b8c9", "handle": "mynewsletter" },
  "data": {
    "subscriber": {
      "id": "6740c1f2a9b8e4d3c2b1a0f9",
      "email": "[email protected]",
      "firstName": "Lina",
      "lastName": "",
      "language": "ar",
      "status": "active",
      "tags": ["vip"],
      "lists": ["6731aa04c2e9d8f7b6a5e4d3"],
      "source": "api",
      "sourceRef": "wordpress-footer",
      "createdAt": "2026-11-18T10:00:00.000Z",
      "updatedAt": "2026-11-18T10:00:00.000Z",
      "unsubscribedAt": null,
      "confirmationSentAt": null,
      "engagement": { "opens": 12, "clicks": 3, "lastOpenedAt": "2026-11-17T08:12:00.000Z", "lastClickedAt": "2026-11-10T19:40:00.000Z" }
    }
  }
}

For subscriber events data holds the same subscriber object the API returns. subscribers.imported holds source, imported, updated, alreadyExisted, skipped and listIds. newsletter.sent holds newsletter (the newsletter object) and recipients.

Verify the signature

The signature is HMAC-SHA256 with your secret over t + "." + the raw body, as hex. Always do four things: sign the body exactly as it arrived (before JSON parsing), refuse a t more than 300 seconds from now, compare in constant time, and ignore an event id you already handled.

Node.js (Express)
import crypto from "node:crypto";
import express from "express";

const SECRET = process.env.MUJAZ_WEBHOOK_SECRET; // "whsec_…"
const app = express();

// express.raw: sign the body exactly as it arrived, before any JSON parsing.
app.post("/hooks/mujaz", express.raw({ type: "application/json" }), (req, res) => {
  const parts = (req.get("Mujaz-Signature") || "").split(",");
  const t = Number((parts.find((p) => p.startsWith("t=")) || "t=0").slice(2));
  const signatures = parts.filter((p) => p.startsWith("v1=")).map((p) => p.slice(3));

  // Refuse old or future timestamps (replays).
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return res.status(400).end();

  const expected = crypto
    .createHmac("sha256", SECRET)
    .update(t + ".")
    .update(req.body)
    .digest("hex");

  // During a secret roll there are two v1= values: accept either.
  const ok = signatures.some(
    (sig) =>
      sig.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
  );
  if (!ok) return res.status(400).end();

  const event = JSON.parse(req.body.toString("utf8"));
  // Delivery is at-least-once: skip an event.id you already handled,
  // then do your work with event.type and event.data.
  res.status(200).end();
});
PHP
<?php
$secret = getenv('MUJAZ_WEBHOOK_SECRET'); // "whsec_…"
$payload = file_get_contents('php://input'); // the raw body
$header = $_SERVER['HTTP_MUJAZ_SIGNATURE'] ?? '';

$t = 0;
$signatures = [];
foreach (explode(',', $header) as $part) {
    [$key, $value] = array_pad(explode('=', trim($part), 2), 2, '');
    if ($key === 't') $t = (int) $value;
    if ($key === 'v1') $signatures[] = $value;
}

// Refuse old or future timestamps (replays).
if (!$t || abs(time() - $t) > 300) {
    http_response_code(400);
    exit;
}

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

// During a secret roll there are two v1= values: accept either.
$ok = false;
foreach ($signatures as $signature) {
    if (hash_equals($expected, $signature)) $ok = true;
}
if (!$ok) {
    http_response_code(400);
    exit;
}

$event = json_decode($payload, true);
// Delivery is at-least-once: skip an $event['id'] you already handled.
http_response_code(200);
Python (Flask)
import hashlib, hmac, os, time
from flask import Flask, abort, request

SECRET = os.environ["MUJAZ_WEBHOOK_SECRET"].encode()  # "whsec_…"
app = Flask(__name__)

@app.post("/hooks/mujaz")
def mujaz_webhook():
    payload = request.get_data()  # the raw body, before any JSON parsing
    t, signatures = 0, []
    for part in request.headers.get("Mujaz-Signature", "").split(","):
        key, _, value = part.strip().partition("=")
        if key == "t" and value.isdigit():
            t = int(value)
        elif key == "v1":
            signatures.append(value)

    # Refuse old or future timestamps (replays).
    if not t or abs(time.time() - t) > 300:
        abort(400)

    expected = hmac.new(SECRET, str(t).encode() + b"." + payload, hashlib.sha256).hexdigest()

    # During a secret roll there are two v1= values: accept either.
    if not any(hmac.compare_digest(expected, s) for s in signatures):
        abort(400)

    event = request.get_json()
    # Delivery is at-least-once: skip an event["id"] you already handled.
    return "", 200

Test your code

With these values your code must compute exactly this signature. The body is the single line as shown, with no extra spaces and no newline at the end.

test vector
secret     whsec_test_secret
t          1763460000
raw body   {"id":"evt_0123456789abcdef01234567","type":"ping","createdAt":"2026-11-18T10:00:00.000Z","apiVersion":"v1","workspace":{"id":"6740aaaaaaaaaaaaaaaaaaaa","handle":"mynewsletter"},"data":{}}

signed     1763460000.<raw body>
v1         a0eac7d4ee02a92a3f2023a639445d8bf8bf641b12139d85bb1ce59219ef30bc

Mujaz-Signature: t=1763460000,v1=a0eac7d4ee02a92a3f2023a639445d8bf8bf641b12139d85bb1ce59219ef30bc

Retries and disabling

  • Any 2xx answer within 10 seconds is a success. Anything else is a failure.
  • We retry after 1 minute, then 5 minutes, 30 minutes, 2 hours, 6, 12 and 24 hours: 8 attempts over about 45 hours.
  • Delivery is at-least-once and order isn't guaranteed: an event may arrive twice, so rely on Mujaz-Event-Id.
  • A 410 Gone answer disables the address at once. If an address keeps failing for 3 days (at least 10 attempts) we disable it and email the account owner. Fix it, then turn it back on in Settings.
  • The delivery log in Settings keeps 30 days: time, type, status, HTTP code, duration and the first 500 characters of your server's answer, with a “Resend” button.

Rolling the secret

“Roll secret” makes a new secret, shown once. For 24 hours we sign with both (two v1= values in the header), so you can move your server to the new secret without missing an event.