امنیت وب‌هوک: امضا، برچسب زمانی و حذف تکرار

نشانی وب‌هوک شما عمومی است؛ یعنی هر کسی می‌تواند به آن درخواست بفرستد. اگر بدون بررسی، رویداد «پرداخت موفق» را بپذیرید، مهاجم می‌تواند سفارش‌ها را بدون پرداخت تأییدشده جلوه دهد.

۱. امضا را بررسی کنید

هر وب‌هوک شی‌پی هدر Sheypay-Signature با قالب t=زمان,v1=امضا دارد. امضا، HMAC-SHA256 رشته {t}.{بدنه خام} با کلید امضای اختصاصی آن endpoint است. حتماً روی بدنه خام (پیش از parse) محاسبه کنید و با مقایسه زمان-ثابت تطبیق دهید.

۲. برچسب زمانی را محدود کنید

درخواست‌هایی با برچسب زمانی بیش از ۵ دقیقه اختلاف را رد کنید. این کار جلوی پخش مجدد (replay) یک وب‌هوک قدیمی معتبر را می‌گیرد.

۳. تکرار را حذف کنید

وب‌هوک ممکن است بیش از یک بار برسد (مثلاً اگر پاسخ شما دیر برسد). شناسه Sheypay-Event-Id (همان id بدنه) را ذخیره کنید و رویداد تکراری را فقط با ۲۰۰ پاسخ دهید.

$raw = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_SHEYPAY_SIGNATURE'] ?? ''), $p);
$ok = isset($p['v1']) && hash_equals(hash_hmac('sha256', $p['t'] . '.' . $raw, $secret), $p['v1'])
   && abs(time() - (int) $p['t']) <= 300;

یک نکته مهم

وب‌هوک برای اطلاع‌رسانی است، نه جایگزین verify. حتی با وب‌هوک معتبر، برای نهایی کردن سفارش verify را صدا بزنید یا وضعیت را با GET /api/v1/payments/:id استعلام کنید.

مستندات کامل: وب‌هوک‌ها