وب‌هوک‌ها
رویدادهای پرداخت را به‌صورت غیرهمزمان روی سرور خود دریافت کنید و وضعیت پرداخت‌ها را با برنامه خود همگام نگه دارید.
نمای کلی
crptoX هنگام رخ دادن یک رویداد پرداخت که برای دریافت آن مشترک شده‌اید، یک درخواست وب‌هوک به آدرس تنظیم‌شده برای حساب درگاه شما ارسال می‌کند.
ارسال وب‌هوک‌ها به‌صورت غیرهمزمان انجام می‌شود. اگر مقصد یک خطای موقت برگرداند، crptoX ارسال را طبق برنامه تلاش مجدد به‌صورت خودکار تکرار می‌کند.
رویدادها
رویدادهای پرداخت موردنظر خود را برای دریافت انتخاب کنید. رویدادها هنگام تغییر وضعیت متناظر Payment Request ایجاد می‌شوند.
payment.confirming
یک پرداخت شناسایی‌شده وارد فرآیند تأیید شده است.
payment.paid
پرداخت به تعداد تأییدهای موردنیاز رسیده و به‌عنوان پرداخت‌شده ثبت شده است.
payment.underpaid
مبلغ پرداخت شناسایی‌شده کمتر از مبلغ موردنیاز فاکتور است.
payment.overpaid
مبلغ پرداخت شناسایی‌شده بیشتر از مبلغ موردنیاز فاکتور است.
payment.expired
Payment Request پیش از تکمیل یک پرداخت معتبر منقضی شده است.
هدرهای درخواست
هر درخواست وب‌هوک شامل هدرهای HTTP زیر است.
Content-Type
application/json
Accept
application/json
User-Agent
crptoX-Webhook/1.0
X-crptoX-Timestamp
تایم‌استمپ Unix که زمان ایجاد درخواست وب‌هوک را مشخص می‌کند.
X-crptoX-Signature
sha256=امضای HMAC-SHA256 که بر اساس تایم‌استمپ و بدنه خام و دقیق درخواست JSON ایجاد شده است.
تأیید امضا
هر درخواست وب‌هوک با استفاده از Webhook Secret شما و الگوریتم HMAC-SHA256 امضا می‌شود. پیش از پردازش payload، امضای درخواست را بررسی کنید.
امضا با استفاده از HMAC-SHA256 و Webhook Secret شما به‌عنوان کلید امضاکننده ایجاد می‌شود.
TIMESTAMP.RAW_JSON_REQUEST_BODYپیام امضاشده شامل تایم‌استمپ Unix، سپس یک نقطه و پس از آن بدنه خام و دقیق JSON درخواست است.
$signature = hash_hmac(
'sha256',
"{$timestamp}.{$rawBody}",
$webhookSecret,
);sha256=SIGNATUREPayload وب‌هوک
درخواست‌های وب‌هوک شامل یک payload از نوع JSON هستند که رویداد پرداخت و فاکتور مرتبط با آن را توصیف می‌کند.
{
"id": "42a869de-03e2-4701-a938-423996ce3065",
"type": "payment",
"event": "paid",
"created_at": "2026-09-10T21:30:00.000000Z",
"payment": {
"id": "42a869de-03e2-4701-a938-423996ce3065",
"status": "paid",
"network": "tron",
"asset": "usdt",
"amount": "10.000000",
"expires_at": "2026-09-10T22:00:00.000000Z"
},
"invoice": {
"id": "e075d503-6d3e-4cf7-b2f2-a449a9c58dc9",
"status": "paid"
}
}فیلدهای Payload
id
شناسه یکتای Payment Request.
type
نوع منبع. در حال حاضر مقدار این فیلد payment است.
event
رویداد پرداختی که باعث ایجاد وب‌هوک شده است.
created_at
تایم‌استمپ ISO 8601 که زمان ایجاد Payment Request را مشخص می‌کند.
payment
اطلاعات Payment Request شامل وضعیت، شبکه، دارایی، مبلغ و زمان انقضا.
invoice
اطلاعات فاکتور مرتبط شامل شناسه یکتا و وضعیت فعلی آن.
ارسال و تلاش مجدد
ارسال وب‌هوک‌ها به‌صورت غیرهمزمان انجام می‌شود. پاسخ 2xx به‌عنوان ارسال موفق در نظر گرفته می‌شود. خطاهای اتصال، پاسخ‌های HTTP 408، HTTP 429 و HTTP 5xx خطاهای موقت محسوب شده و ممکن است باعث تلاش مجدد شوند.
هر Delivery در مجموع حداکثر پنج بار تلاش می‌شود. اگر تمام تلاش‌ها ناموفق باشند، وضعیت Delivery به failed تغییر می‌کند.
پاسخ‌های HTTP
پاسخی که endpoint وب‌هوک شما برمی‌گرداند مشخص می‌کند که ارسال موفق بوده یا باید مجدداً تلاش شود.
2xx
وب‌هوک با موفقیت تحویل داده شده است.
408 / 429
ارسال پس از تأخیر تعیین‌شده مجدداً تلاش می‌شود.
5xx
ارسال پس از تأخیر تعیین‌شده مجدداً تلاش می‌شود.
Other 4xx
ارسال ناموفق ثبت می‌شود و به‌صورت خودکار مجدداً تلاش نخواهد شد.
بررسی وب‌هوک
بدنه خام درخواست را دریافت کنید، پیام امضاشده را با استفاده از هدر timestamp بسازید و امضای محاسبه‌شده را با هدر X-crptoX-Signature با استفاده از مقایسه ثابت‌زمان بررسی کنید.
$timestamp = request()->header('X-crptoX-Timestamp');
$signature = request()->header('X-crptoX-Signature');
$rawBody = request()->getContent();
$expected = 'sha256=' . hash_hmac(
'sha256',
"{$timestamp}.{$rawBody}",
$webhookSecret,
);
if (! hash_equals($expected, $signature)) {
abort(401);
}