Real-time events
وبهوک ها: مبانی
نویدا رویدادهای OTP را با POST امضاشده به endpoint شما ارسال می کند.
وبهوک چیست
وبهوک یک درخواست HTTP از سمت نویدا به آدرس محصول شماست. به جای polling، دریافت رویدادهایی مثل ارسال موفق یک تلاش، شکست ارسال، تایید کاربر یا انقضا از همین مسیر انجام می شود.
نیازمندی endpoint
- ۱URL عمومی HTTPSدر محیط production فقط HTTPS پذیرفته می شود و آدرس های localhost یا شبکه خصوصی معتبر نیستند.
- ۲پذیرش POST JSONنویدا payload رویداد را با متد POST و هدر
application/jsonارسال می کند. - ۳دسترسی به raw bodyبررسی امضا باید روی بدنه خام درخواست انجام شود، نه روی JSON parse شده.
- ۴پاسخ ۲xxهر پاسخ ۲xx به معنی تحویل موفق است. پاسخ های دیگر وارد چرخه تلاش دوباره می شوند.
هدرها
| هدر | نمونه | توضیح |
|---|---|---|
Navidaa-Signature | t=1748000000,v1=... | امضای HMAC درخواست. مقدار t timestamp است و هر v1 یک امضای قابل قبول است. |
Navidaa-Timestamp | 1748000000 | همان timestamp داخل امضا، برای بررسی تازگی درخواست. |
Navidaa-Event-Id | a1b2... | شناسه یکتای رویداد. در تلاش های دوباره همان رویداد ثابت می ماند و برای جلوگیری از پردازش تکراری مناسب است. |
Navidaa-Event-Type | otp.verified | نوع رویداد. با فیلد event در بدنه یکی است. |
Navidaa-Attempt | 1 | شماره تلاش ارسال همین وبهوک. مقدار از ۱ شروع می شود و با هر تلاش دوباره بیشتر می شود. |
User-Agent | Navidaa-Webhook/1.0 | شناسه ارسال کننده وبهوک. |
امضا
این قطعه نشان می دهد مقدار قابل امضا چگونه ساخته می شود: timestamp از هدر خوانده می شود، با یک نقطه و بدنه خام درخواست ترکیب می شود، سپس با secret همان endpoint امضای HMAC-SHA256 ساخته می شود. نتیجه باید با یکی از مقدارهای v1 در هدر مقایسه شود.
signed_payload = f"{timestamp}.".encode() + raw_body
expected = hmac_sha256(webhook_secret, signed_payload).hex()
# Compare expected with each v1 signature in constant time.