دریافت وب‌هوک امضاشده

ساخت کانال وب‌هوک

1. 1

   یک مسیر عمومی HTTPS آماده کنید

   گواهی معتبر روی پورت ۴۴۳ داشته باشید. مقصد خصوصی، لوپ‌بک، رزروشده یا ناامن پذیرفته نمی‌شود.

2. 2

   کانال را اضافه کنید

   از بخش هشدارها، وب‌هوک را انتخاب کنید، نشانی و زبان پیام را وارد و ذخیره کنید.

3. 3

   کلید امضا را امن نگه دارید

   کلید هنگام ساخت کانال نمایش داده می‌شود. پیش از ترک صفحه آن را در محل نگهداری اسرار قرار دهید.

4. 4

   پیام آزمایشی بفرستید

   آزمون کانال را اجرا کنید و مطمئن شوید مسیر شما امضا را تأیید و پاسخ موفق برمی‌گرداند.

هدرهای درخواست

بررسی امضا

هدر زمان و امضا را بخوانید، بایت‌های خام بدنه را نگه دارید و با کلید کانال خود HMAC-SHA256 را روی «زمان + نقطه + بدنه خام» محاسبه کنید. مقایسه باید با تابع مقاوم در برابر سنجش زمان انجام شود.

هدر ناقص یا نامعتبر را رد کنید. زمانی را که بیرون از بازه قابل قبول برنامه شماست نیز نپذیرید؛ پنج دقیقه برای بیشتر اتصال‌ها نقطه شروع مناسبی است.

<?php
$timestamp = $_SERVER['HTTP_X_FLUX_TIMESTAMP'] ?? '';
$received = $_SERVER['HTTP_X_FLUX_SIGNATURE'] ?? '';
$body = file_get_contents('php://input');
$secret = getenv('FLUX_WEBHOOK_SECRET');

if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) {
    http_response_code(401);
    exit;
}

$expected = hash_hmac('sha256', $timestamp.'.'.$body, $secret);
if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true, flags: JSON_THROW_ON_ERROR);
http_response_code(204);

پذیرش ایمن ارسال

فقط پس از پذیرش امن رویداد، پاسخ 2xx بدهید. اگر پردازش چند ثانیه طول می‌کشد، امضا را بررسی کنید، رویداد را در صف بگذارید و سپس پاسخ دهید. درخواست ارسال، مهلت و حجم پاسخ محدودی دارد.

از X-Flux-Delivery به‌عنوان کلید جلوگیری از تکرار استفاده کنید. اگر همان ارسال دوباره رسید، بدون اجرای دوباره عملیات اصلی آن را بپذیرید. پاسخ تغییر مسیر دنبال نمی‌شود.

تلاش دوباره و خطاها

خطای شبکه، پایان مهلت، پاسخ‌های 408، 409، 425، 429 و خطاهای سرور می‌توانند دوباره امتحان شوند. سرویس حداکثر پنج بار و با فاصله تقریبی ۱، ۵، ۱۵ و ۳۰ دقیقه تلاش می‌کند. سایر خطاهای سمت گیرنده نهایی هستند، چون تکرار همان درخواست معمولاً آن‌ها را برطرف نمی‌کند.

پس از آخرین تلاش ناموفق، ارسال برای بررسی در داشبورد ثبت می‌شود. برای درخواست تکراری پذیرفته‌شده پاسخ 2xx پایدار بدهید و فقط وقتی واقعاً به کاهش ترافیک نیاز دارید از 429 استفاده کنید.

فهرست بررسی امنیت مسیر

• فقط درخواست HTTPS با مسیر و روش موردنظر را بپذیرید.
• پیش از خواندن یا اجرای بدنه، زمان و امضا را بررسی کنید.
• از مقایسه امن و بازه جلوگیری از تکرار استفاده کنید.
• با X-Flux-Delivery پردازش تکراری را متوقف کنید.
• پاسخ مسیر را سریع نگه دارید و کار طولانی را به صف بسپارید.
• اگر احتمال افشای کلید وجود دارد، کانال را دوباره بسازید.
• ثبت بدنه را محدود و خطاهای پی‌درپی امضا را بررسی کنید.