Webhooks

كيف تعمل Webhooks

اضبط عنوان webhook من إعدادات لوحة التحكم، وسترسل Authevo إليه حدثًا موقَّعًا.

توجد ثلاثة أنواع أحداث اليوم. يُطلَق otp.status_update مع نقل WhatsApp حالة delivered أو read أو failed لرسالة أرسلتها Authevo نيابةً عنك — تكون الحالة دائمًا واحدة من هذه الثلاث. ويُطلَق otp.telegram_linked مرة واحدة، بأفضل جهد (دون إعادة محاولة دائمة)، بمجرد أن يربط المستلم Telegram بعد فشل إرسال عبر WhatsApp — بالنسبة لفشل عبر /v1/otp/send، تكون Authevo قد سلّمت بالفعل رمزًا جديدًا عبر Telegram تلقائيًا وقت إطلاق هذا الحدث (redelivered: true)، فاستخدمه لتحديث واجهتك في الوقت الفعلي لا لإطلاق التسليم بنفسك. ويُطلَق account.low_balance مرة واحدة، بأفضل جهد (دون إعادة محاولة دائمة)، فور إرسال يترك رصيدك دون الحدّ الأدنى، لتنبيه نفسك قبل فشل الإرسال التالي.

{
  "event": "otp.status_update",
  "meta_message_id": "wamid.HBgLMjAxMjM0NTY3ODkVAgARGBI...",
  "status": "delivered"
}

{
  "event": "otp.telegram_linked",
  "phone_hash": "5e884898da28047151d0e56f8dc6292...",
  "redelivered": true
}

{
  "event": "account.low_balance",
  "balance": 1.42
}

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

يحمل كل طلب webhook ترويسة X-Authevo-Signature بالصيغة sha256=<hex>، حيث القيمة السداسية عشرية هي بصمة HMAC-SHA256 لجسم الطلب الخام، موقَّعة بسر الـ webhook الخاص بك. احذف البادئة sha256= قبل المقارنة. تحقق منها قبل الوثوق بالحمولة.

import { createHmac, timingSafeEqual } from 'node:crypto';

function isValidWebhook(rawBody, signatureHeader, webhookSecret) {
  const expected = createHmac('sha256', webhookSecret).update(rawBody).digest('hex');
  const provided = (signatureHeader || '').replace('sha256=', '');
  const a = Buffer.from(expected);
  const b = Buffer.from(provided);
  return a.length === b.length && timingSafeEqual(a, b);
}

// rawBody must be the exact, unparsed request body — verify BEFORE JSON.parse.
app.post('/webhooks/authevo', (req, res) => {
  const signature = req.headers['x-authevo-signature'];
  if (!isValidWebhook(req.rawBody, signature, process.env.AUTHEVO_WEBHOOK_SECRET)) {
    return res.status(401).end();
  }
  const event = JSON.parse(req.rawBody);
  // handle event.event === 'otp.status_update'
  res.status(200).end();
});

ضبط عنوان الـ webhook

اضبط عنوان الـ webhook من إعدادات لوحة التحكم — يجب أن يكون عنوان https:// عامًّا. ترفض Authevo حفظ عنوان يُحلَّل إلى عنوان IP خاص أو داخلي، ولن تستدعيه حتى تفعل.