المطورون
الـ Webhooks
عندما تتغيّر حالة الفاتورة، ترسل CryBit طلب POST موقّعًا بمحتوى JSON إلى رابط webhook الخاص بتاجرك.
الإعداد
حدّد رابط webhook وفعّل الأحداث في إعدادات التاجر، ضمن تبويب التكامل: paid وexpired وrefunded وcancelled. ويجب أن يكون الرابط عنوان HTTP أو HTTPS عامًا على المنفذ 80 أو 443 أو 8080 أو 8443؛ ولا تُتبع عمليات إعادة التوجيه. ويُحدَّد هذا الرابط على مستوى التاجر، لا في طلب إنشاء الفاتورة.
الترويسات
| الترويسة | القيمة |
|---|---|
X-CryBit-Event | اسم الحدث، مثل payment.paid. |
X-CryBit-Signature | t=<unix time>,v1=<hex>: قيمة HMAC-SHA256 لـ "<t>.<raw body>" باستخدام سر التوقيع الخاص بك. |
تحقّق من التوقيع
يظهر سر التوقيع في إعدادات التاجر بجانب رابط webhook. احسب التوقيع على المحتوى الخام، وقارنه في زمن ثابت، وارفض الطلبات الأقدم من خمس دقائق.
PHP
$secret = getenv('CRYBIT_WEBHOOK_SECRET');
$body = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_CRYBIT_SIGNATURE'] ?? '';
parse_str(str_replace(',', '&', $header), $p); // t=…&v1=…
$t = (int) ($p['t'] ?? 0);
$expected = hash_hmac('sha256', $t . '.' . $body, $secret);
if (abs(time() - $t) > 300 || !hash_equals($expected, $p['v1'] ?? '')) {
http_response_code(400);
exit;
}
// the request is genuine: store the event, answer 200, do the rest later
http_response_code(200);Node.js
import crypto from 'node:crypto'
export function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(',').map((kv) => kv.split('=')))
const t = Number(parts.t)
const expected = crypto.createHmac('sha256', secret).update(t + '.' + rawBody).digest('hex')
const ok = parts.v1 && parts.v1.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
return ok && Math.abs(Date.now() / 1000 - t) <= 300
}التسليم وإعادة المحاولة
- أجب بحالة 2xx بسرعة: تنتظر CryBit نحو اثنتي عشرة ثانية.
- إذا لم تُجب، تعيد CryBit المحاولة بعد 15 ثانية، ثم دقيقة واحدة، ثم 5 و15 و30 دقيقة، ثم 2 و6 و24 ساعة.
- توقف أي استجابة من فئة 4xx، باستثناء 429، إعادة المحاولات.
- يمكن أن يصل الحدث نفسه أكثر من مرة: تعامل معه بطريقة متكررة آمنة (idempotent)، معتمدًا على order_id أو معرّف الفاتورة uuid.
- إذا فاتك webhook، اقرأ الحالة عبر GET /api/v1/payments/{uuid}: فهو دائمًا المصدر الموثوق للمعلومة.
FAQ
هل يمكنني رؤية ما تم تسليمه؟
نعم. تسرد صفحة سجلات API في حساب التاجر الطلبات وعمليات تسليم webhook مع رمز الحالة والمحتوى.
