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. 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. Copy the signing secret (
whsec_…) at once: it is shown in full only once. Keep it in an environment variable on your server. - 3. Press “Send test”: a
pingevent 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
reasonandvia:link,one_click,report,dashboardorapi. - subscriber.bounced
- A subscriber's email bounced, with
bounceType(permanentortransient). 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.
datais empty:{}.
What we send
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…{
"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.
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
$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);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 "", 200Test 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.
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=a0eac7d4ee02a92a3f2023a639445d8bf8bf641b12139d85bb1ce59219ef30bcRetries 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 Goneanswer 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.
