خطافات الويب (Webhooks)
يرسل موجز إلى خادمك طلبًا موقّعًا عند كل حدث يهمّك: مشترك جديد، تأكيد، إلغاء اشتراك، ارتداد، استيراد، أو عدد أُرسل.
الإعداد
- 1. في الإعدادات ← API ← خطافات الويب أضف عنوانًا يبدأ بـ
https://على المنفذ 443، واختر الأحداث التي تريدها. حتى 5 عناوين للحساب (خطة الأعمال). - 2. انسخ سرّ التوقيع (
whsec_…) فورًا: يظهر كاملًا مرة واحدة فقط. احفظه في متغيّر بيئة على خادمك. - 3. اضغط «إرسال اختبار»: يصل حدث
pingوترى رمز HTTP الذي أعاده خادمك ومدة الرد.
لا نقبل عناوين الشبكات الخاصة أو المحلية، ولا عناوين موجز نفسها، ولا منافذ غير 443. ونتحقق من العنوان مجددًا عند كل اتصال.
الأحداث
- subscriber.created
- مشترك جديد من أي طريق: الواجهة، أو لوحة التحكم، أو نموذج الاشتراك. لا يُرسل لشخص موجود أصلًا.
- subscriber.confirmed
- مشترك أكّد بريده (من «بانتظار التأكيد» إلى «فعّال»).
- subscriber.unsubscribed
- إلغاء اشتراك حقيقي، مع
reasonوvia:linkأوone_clickأوreportأوdashboardأوapi. - subscriber.bounced
- ارتدّ بريد المشترك، مع
bounceType(permanentأوtransient). مرة واحدة لكل شخص. - subscriber.complained
- أبلغ المشترك عن رسالة كبريد مزعج. مرة واحدة لكل شخص.
- subscribers.imported
- انتهى استيراد (من لوحة التحكم أو الإضافة الجماعية): حدث واحد بالأرقام، لا حدث لكل صف.
- newsletter.sent
- اكتمل إرسال عدد. مرة واحدة لكل عدد.
- ping
- زر «إرسال اختبار» فقط، إلى ذلك العنوان وحده.
dataفارغة:{}.
ما نرسله
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" }
}
}
}data لأحداث المشتركين فيها كائن المشترك نفسه الذي تعيده الواجهة. وsubscribers.imported فيها source وimported وupdated وalreadyExisted وskipped وlistIds. وnewsletter.sent فيها newsletter (كائن العدد) وrecipients.
التحقق من التوقيع
التوقيع هو HMAC-SHA256 بسرّك على النص t + "." + المحتوى الخام، بصيغة hex. افعل أربعة أشياء دائمًا: وقّع المحتوى كما وصل (قبل تحويله من JSON)، وارفض t الأبعد من 300 ثانية عن الآن، وقارن بزمن ثابت، وتجاهل id حدث عالجته من قبل.
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 "", 200اختبر شيفرتك
بهذه القيم يجب أن تحسب شيفرتك التوقيع التالي بالضبط. المحتوى سطر واحد كما هو، بلا مسافات زائدة ولا سطر جديد في آخره.
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إعادة المحاولة والتعطيل
- أي رد بين 200 و299 خلال 10 ثوانٍ نجاح. غير ذلك فشل.
- نعيد المحاولة بعد دقيقة، ثم 5 دقائق، ثم 30 دقيقة، ثم ساعتين، ثم 6، ثم 12، ثم 24 ساعة: 8 محاولات خلال نحو 45 ساعة.
- التسليم «مرة على الأقل» والترتيب غير مضمون: قد يصل الحدث مرتين، فاعتمد على
Mujaz-Event-Id. - رد
410 Goneيعطّل العنوان فورًا. وإن فشل العنوان 3 أيام متتالية (10 محاولات على الأقل) نعطّله ونراسل مالك الحساب. أصلحه ثم أعد تفعيله من الإعدادات. - سجلّ التسليم في الإعدادات يحفظ آخر 30 يومًا: الوقت والنوع والحالة ورمز HTTP والمدة وأول 500 حرف من رد خادمك، وزر «إعادة الإرسال».
تغيير السرّ
«تغيير السرّ» يصنع سرًّا جديدًا يظهر مرة واحدة. لمدة 24 ساعة نوقّع بالسرّين معًا (قيمتا v1= في الترويسة)، فتنقل خادمك إلى السرّ الجديد دون أن يفوتك حدث.
