Webhooks
إشعارات فورية موقّعة لأحداث الفواتير.
الأحداث
invoice.paid– تم رصد المبلغ كاملاً (ليس نهائياً بعد)invoice.confirmed– الدفع نهائي، قم بتسليم الطلبinvoice.partially_paid– دفع جزئيinvoice.overpaid– دفع زائدinvoice.expired– انتهت الصلاحيةinvoice.late_payment– دفعة وصلت بعد انتهاء الصلاحيةinvoice.cancelled– ملغاة
محتوى الرسالة
{
"id": "evt_3k9d0s8f7g6h5j4k3l2m",
"type": "invoice.confirmed",
"created_at": "2026-01-01T12:04:10Z",
"livemode": false,
"data": {
"id": "inv_8c1k2m9q4w7e3r5t6y0u",
"status": "confirmed",
"order_id": "1001",
"amount": "25.000000",
"amount_paid": "25.000000",
"network": "trc20",
"address": "TJ8w2sQYk6n8cW3nVvG6kP2cXxH9Lm4b7R",
"transactions": [
{ "tx_hash": "9f2c…", "amount": "25.000000", "confirmations": 19, "status": "confirmed" }
]
}
}التحقق من التوقيع
يحمل كل طلب الترويسة X-Timestamp (ثوانٍ Unix) وX-Signature = hex(HMAC-SHA256(secret, timestamp + "." + raw_body)). ارفض أي طلب يزيد عمر توقيته عن 5 دقائق.
<?php
$secret = 'whsec_your_webhook_secret';
$payload = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
// 1. Reject old or future timestamps (replay protection, 5 minutes)
if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) {
http_response_code(400);
exit('stale');
}
// 2. Compute and compare the signature in constant time
$expected = hash_hmac('sha256', $timestamp . '.' . $payload, $secret);
if (!hash_equals($expected, $signature)) {
http_response_code(401);
exit('bad signature');
}
$event = json_decode($payload, true);
if ($event['type'] === 'invoice.confirmed') {
// Mark order $event['data']['order_id'] as paid (idempotently!)
}
http_response_code(200);
echo 'ok';import crypto from 'node:crypto';
import express from 'express';
const app = express();
const SECRET = 'whsec_your_webhook_secret';
app.post('/webhooks/gateway', express.raw({ type: 'application/json' }), (req, res) => {
const ts = req.get('X-Timestamp') || '';
const sig = req.get('X-Signature') || '';
if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
return res.status(400).send('stale');
}
const expected = crypto.createHmac('sha256', SECRET)
.update(ts + '.' + req.body.toString('utf8'))
.digest('hex');
const ok = sig.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
if (!ok) return res.status(401).send('bad signature');
const event = JSON.parse(req.body.toString('utf8'));
if (event.type === 'invoice.confirmed') {
// fulfil the order event.data.order_id
}
res.send('ok');
});إعادة المحاولة
أعد أي استجابة 2xx خلال 10 ثوانٍ، وإلا فسنعيد المحاولة بعد دقيقة، 5 دقائق، 15 دقيقة، ساعة، 6 ساعات، و24 ساعة. كل محاولة تظهر في لوحة التحكم ← Webhooks ← سجل الإرسال حيث يمكنك إعادة الإرسال يدوياً أو إرسال حدث تجريبي.
قد تصل الأحداث أكثر من مرة أو بترتيب مختلف: اجعل المعالج لديك آمناً ضد التكرار باستخدام id الحدث، واعتمد دائماً على آخر status للفاتورة.
تحتاج مساعدة؟ تواصل معنا
آخر تحديث: 17 نوفمبر 2026 م