تفاعل لحظيًا عبر خطافات موقّعة
اشترك في أحداث التحقّق، استقبل حمولات JSON موقّعة، واعتمد على إعادة المحاولة التلقائية بمعدّل أُسّي.
أنواع الأحداث
كل تسليم يحمل نوع حدث ثابتًا. اشترك في ما يلزمك فقط.
| الحدث | الوصف |
|---|---|
| otp.sent | تمّ إرسال OTP إلى القناة المختارة. |
| otp.delivered | أكّد المزوّد التسليم إلى جهاز المستخدم. |
| otp.verified | أدخل المستخدم الرمز الصحيح وتمّ التحقّق منه بنجاح. |
| otp.failed | فشل التسليم أو التحقّق — راجع الحمولة لمعرفة السبب. |
| otp.expired | انتهت صلاحية الرمز قبل أن يدخله المستخدم. |
هيكل الحمولة
كل حمولات Webhook تتشارك نفس الهيكل: معرّف الحدث، نوعه، طابع زمني، وكائن بيانات بأنواع محدّدة.
json
{
"id": "evt_2KqLxY9z3a",
"type": "otp.verified",
"created_at": "2026-05-03T10:14:22Z",
"data": {
"id": "otp_8f2c1a9b4d",
"channel": "sms",
"phone": "+9665XXXXXXXX",
"status": "verified",
"verified_at": "2026-05-03T10:14:21Z"
}
}تحقّق من التوقيع
كل طلب يحمل ترويسة Authentica-Signature. تحقّق منها بـ HMAC-SHA256 ومقارنة آمنة زمنيًا قبل الوثوق بالحمولة.
typescript
import crypto from "node:crypto";
// Header sent by Authentica on every webhook delivery:
// Authentica-Signature: t=1714723200,v1=4f8c…
export function verifyWebhook(rawBody: string, header: string, secret: string) {
const parts = Object.fromEntries(header.split(",").map(p => p.split("=")));
const signedPayload = `${parts.t}.${rawBody}`;
const expected = crypto
.createHmac("sha256", secret)
.update(signedPayload)
.digest("hex");
const ok = crypto.timingSafeEqual(
Buffer.from(expected, "hex"),
Buffer.from(parts.v1, "hex"),
);
if (!ok) throw new Error("Invalid signature");
return JSON.parse(rawBody);
}سياسة إعادة المحاولة
نعتبر أي استجابة خارج النطاق 2xx (أو انتهاء المهلة) فشلاً ونعيد المحاولة تلقائيًا.
- تأخير أُسّي: إعادة المحاولة عند 30 ثانية، 2 دقيقة، 10 دقائق، ساعة، و6 ساعات.
- حتى 5 محاولات على مدى 24 ساعة قبل إسقاط الحدث.
- كل إعادة محاولة تستخدم توقيعًا جديدًا بطابع زمني محدَّث.
- التسليمات الفاشلة تظهر في لوحة التحكم لإعادة الإطلاق يدويًا.