تخطَّ إلى المحتوى

التحقق من التوقيعات

كل طلب Webhook موقَّع بسر التوقيع الخاص باشتراكك (whsec_...، ويظهر مرة واحدة حين تنشئ الاشتراك أو تغيّر السر). تحقّق من كل طلب قبل أن تثق به.

signed_payload = X-AD80-Timestamp + "." + X-AD80-Delivery + "." + raw_body
signature = hex( HMAC-SHA256( secret, signed_payload ) )
X-AD80-Signature: v1=<signature>[,v1=<signature of the second secret>]

خطوات التحقق:

  1. اقرأ المحتوى الخام للطلب كبايتات، كما وصل تماماً. لا تحلّل JSON ثم تعيد تسلسله قبل ذلك.
  2. اقرأ X-AD80-Timestamp وX-AD80-Delivery وX-AD80-Signature.
  3. ارفض الطلب إن كان الطابع الزمني يبعد أكثر من 5 دقائق عن ساعتك (في أي اتجاه). هذه هي نافذة منع إعادة الإرسال.
  4. احسب HMAC-SHA256 للنص timestamp + "." + deliveryId + "." + rawBody بسرّك، بصيغة hex بأحرف صغيرة.
  5. اقبل الطلب إن ساوت النتيجة أي إدخال v1= في X-AD80-Signature (وقارن بزمن ثابت). أثناء تغيير السر تحمل الترويسة إدخالين، وقد يكون لديك سرّان: اقبل أي تطابق بين أي إدخال وأي سرّ من أسرارك.
  6. ردّ بـ 2xx بسرعة، ثم عالج الطلب. وامنع التكرار اعتماداً على X-AD80-Delivery (راجع التسليم وإعادة المحاولة ومنع التكرار).
// Node 18+, Express 4 or 5. npm install express
import crypto from 'node:crypto';
import express from 'express';
// During a rotation, list both secrets until you have called retire-secrets.
const SECRETS = [process.env.AD80_WEBHOOK_SECRET];
const REPLAY_WINDOW_S = 300;
function verifyAd80(rawBody, timestamp, deliveryId, signatureHeader) {
const ts = Number(timestamp);
if (!Number.isInteger(ts) || Math.abs(Date.now() / 1000 - ts) > REPLAY_WINDOW_S) return false;
const given = (signatureHeader || '')
.split(',')
.map((s) => s.trim())
.filter((s) => s.startsWith('v1='))
.map((s) => Buffer.from(s.slice(3), 'hex'));
for (const secret of SECRETS) {
const want = crypto
.createHmac('sha256', secret)
.update(`${timestamp}.${deliveryId}.`)
.update(rawBody)
.digest();
if (given.some((g) => g.length === want.length && crypto.timingSafeEqual(g, want))) return true;
}
return false;
}
const app = express();
// express.raw keeps the exact bytes; do not use express.json() on this route.
app.post('/webhooks/ad80', express.raw({ type: 'application/json' }), (req, res) => {
const ok = verifyAd80(
req.body,
req.get('X-AD80-Timestamp'),
req.get('X-AD80-Delivery'),
req.get('X-AD80-Signature'),
);
if (!ok) return res.status(401).send('bad signature');
const deliveryId = req.get('X-AD80-Delivery');
const event = JSON.parse(req.body.toString('utf8'));
// TODO: skip if deliveryId was already processed, else store it and queue the work.
console.log(deliveryId, event.type);
res.sendStatus(204);
});
app.listen(3000);
  • التحقق من JSON بعد تحليله. أطر العمل التي تحلّل المحتوى نيابة عنك تغيّر المسافات وترتيب المفاتيح. وقّع دائماً على البايتات الخام.
  • نسيان معرّف التسليم. النص الموقَّع هو timestamp.deliveryId.body، وليس timestamp.body.
  • فحص أول إدخال v1= فقط. أثناء تغيير السر تحمل الترويسة توقيعين.
  • المقارنة بـ ==. استخدم مقارنة بزمن ثابت.
  • ساعة خادم غير مضبوطة. أبقِ ساعتك متزامنة (NTP)، وإلا وقعت طلبات صحيحة خارج نافذة الدقائق الخمس.