پرش به محتوای اصلی
شی‌پی
ورود

وب‌هوک‌ها

رویدادها، امضا و تلاش مجدد.

وب‌هوک‌ها تغییرات مهم را بلافاصله به سرور شما اطلاع می‌دهند. آدرس‌ها را در پنل، بخش «وب‌هوک‌ها» و جداگانه برای حالت آزمایشی و عملیاتی تعریف کنید (حداکثر ۱۰ آدرس).

قالب درخواست

http
POST /webhooks/sheypay HTTP/1.1
Content-Type: application/json
Sheypay-Signature: t=1791014400,v1=5f2c…e91a
Sheypay-Event-Id: 0199a4f3-0b7e-71c2-8a44-2d6b1f0c9a11
Sheypay-Event-Type: payment.verified
Sheypay-Delivery-Attempt: 1

{
  "id": "0199a4f3-0b7e-71c2-8a44-2d6b1f0c9a11",
  "type": "payment.verified",
  "created_at": "2026-10-03T08:05:12.000Z",
  "mode": "test",
  "data": { "id": "0199a4f2-…", "status": "verified", "amount": 1500000, "fee": 15000, "merchant_reference": "ORDER-1042-1", "tracking_code": "10000123", "...": "..." }
}

رویدادها

payment.createdپرداخت ایجاد شد
payment.pendingپرداخت در انتظار نتیجه است
payment.successپرداخت موفق شد (نیازمند تأیید پذیرنده)
payment.verifiedپرداخت توسط پذیرنده تأیید شد
payment.failedپرداخت ناموفق شد
payment.expiredپرداخت منقضی شد
payment.reversedپرداخت برگشت خورد
payment.refundedپرداخت مسترد شد
settlement.createdتسویه ایجاد شد
settlement.completedتسویه انجام شد
settlement.failedتسویه ناموفق شد
invoice.paidفاکتور پرداخت شد
payment_link.paidلینک پرداخت پرداخت شد
subscription.createdاشتراک ایجاد شد
subscription.renewedاشتراک تمدید شد
subscription.failedتمدید اشتراک ناموفق شد
subscription.cancelledاشتراک لغو شد

برای دریافت همه رویدادها، * را انتخاب کنید. یک رویداد آزمایشی ping هم از پنل قابل ارسال است.

بررسی امضا

هدر Sheypay-Signature به شکل t=<unix>,v1=<hex> است. مقدار v1 برابر HMAC-SHA256(secret, "<t>.<بدنه خام>") است. کلید امضا (whsec_…) هنگام ساخت endpoint فقط یک بار نمایش داده می‌شود و قابل چرخش است.

php
<?php
$raw = file_get_contents('php://input');          // بدنه خام، قبل از json_decode
$header = $_SERVER['HTTP_SHEYPAY_SIGNATURE'] ?? '';
parse_str(str_replace(',', '&', $header), $parts); // t=...&v1=...
$secret = getenv('SHEYPAY_WEBHOOK_SECRET');         // whsec_...

$expected = hash_hmac('sha256', $parts['t'] . '.' . $raw, $secret);
if (!isset($parts['v1']) || !hash_equals($expected, $parts['v1']) || abs(time() - (int) $parts['t']) > 300) {
    http_response_code(400);
    exit;
}
$event = json_decode($raw, true);
if (alreadyProcessed($event['id'])) { http_response_code(200); exit; } // Sheypay-Event-Id
handleEvent($event['type'], $event['data']);
http_response_code(200);
  • امضا را روی بدنه خام و با مقایسه زمان‌ثابت بررسی کنید.
  • برچسب زمانی با بیش از ۵ دقیقه اختلاف را رد کنید (ضد replay).
  • رویدادها را با Sheypay-Event-Id حذف تکرار کنید؛ یک رویداد ممکن است بیش از یک بار برسد.
  • سریع (زیر ۱۰ ثانیه) با کد 2xx پاسخ دهید و پردازش سنگین را در صف انجام دهید.

تلاش مجدد

اگر پاسخ 2xx دریافت نشود، ارسال پس از ۱ دقیقه، ۵ دقیقه، ۳۰ دقیقه، ۲ ساعت، ۶ ساعت، ۱۲ ساعت و ۲۴ ساعت تکرار می‌شود. شماره تلاش در هدر Sheypay-Delivery-Attempt است. پس از آخرین تلاش، تحویل «ناموفق» علامت می‌خورد و از پنل قابل ارسال مجدد است. آدرسی که ۱۰۰ بار پیاپی خطا دهد غیرفعال و به شما اطلاع داده می‌شود.

وب‌هوک جایگزین verify نیست. برای نهایی کردن سفارش همچنان verify را صدا بزنید.

آدرس وب‌هوک باید عمومی باشد؛ آدرس‌های داخلی، localhost و IPهای خصوصی پذیرفته نمی‌شوند. در حالت عملیاتی https الزامی است.