Developer Webhook API ও Delivery

ওয়েবহুকের মাধ্যমে পোলিং না করে ISPbills থেকে আপনার সার্ভারে ইভেন্ট পাওয়া যায়। API v2 বা API Management স্ক্রিন থেকে এন্ডপয়েন্ট পরিচালনা করুন।

অপারেটরদের screen-based সেটআপ ও non-code overview-এর জন্য অ্যাডমিন Webhook সেটআপ দেখুন।

এন্ডপয়েন্ট নিবন্ধন

রিকোয়েস্ট ফিল্ডের নাম events_json:

POST /api/v2/webhooks
Authorization: Bearer YOUR_V2_TOKEN
Accept: application/json
Content-Type: application/json

{
  "url": "https://integration.example.com/webhooks/ispbills",
  "events_json": ["customer.created", "payment.received"],
  "is_active": true
}

তৈরির রেসপন্সে secret একবার দেওয়া হয়। সেটি সঙ্গে সঙ্গে সার্ভার-সাইড সিক্রেট ম্যানেজারে সংরক্ষণ করুন। তালিকা রেসপন্সে সিক্রেট ফেরত আসে না।

ব্যবস্থাপনা রুট

ইভেন্ট

বর্তমান API Management স্ক্রিনে আছে:

• customer.created, customer.updated, customer.deleted
• customer.suspended, customer.renewed
• bill.created, invoice.generated
• payment.received, payment.failed
• subscription.expired
• * — সব পাঠানো ইভেন্ট

অজানা নতুন ইভেন্ট নিরাপদে উপেক্ষা করার ব্যবস্থা রাখুন।

ডেলিভারি

ISPbills নিচের হেডারসহ HTTP POST পাঠায়:

Content-Type: application/json
X-Webhook-Event: customer.created
X-Webhook-Signature: sha256=HEX_HMAC_DIGEST

{
  "event": "customer.created",
  "timestamp": "2026-08-16T12:00:00.000000Z",
  "data": {
    "id": 1234,
    "name": "Example Customer",
    "status": "active"
  }
}

স্বাক্ষর যাচাই

JSON পার্স করার আগে হুবহু raw request body দিয়ে HMAC-SHA256 হিসাব করুন:

$rawBody = file_get_contents('php://input');
$received = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $webhookSecret);

if (! hash_equals($expected, $received)) {
    http_response_code(401);
    exit('Invalid signature');
}

পার্স করে পুনরায় JSON বানানো body দিয়ে স্বাক্ষর হিসাব করবেন না। টাইমিং-সেফ তুলনা ব্যবহার করুন।

রিট্রাই ও নিরাপত্তা

ওয়েবহুক ডেলিভারি কিউতে অ্যাসিঙ্ক্রোনাসভাবে চলে। প্রতিটি ডেলিভারিতে 15-সেকেন্ডের রিকোয়েস্ট টাইমআউট থাকে। ব্যর্থ ডেলিভারি সর্বোচ্চ তিনবার চেষ্টা করা হয়, কিউ করা রিট্রাইগুলো আনুমানিক 30, 60 ও 120 সেকেন্ড ব্যবধানে হয়। দ্রুত 2xx রেসপন্স দিয়ে ভারী কাজ কিউতে করুন। একই ইভেন্ট একাধিকবার আসতে পারে, তাই হ্যান্ডলার idempotent করুন।

• বৈধ সার্টিফিকেটসহ HTTPS URL ব্যবহার করুন।
• সিক্রেট লগ বা সোর্স কোডে রাখবেন না।
• অজানা JSON ফিল্ড গ্রহণ করুন।
• নন-2xx রেসপন্স ও লেটেন্সি মনিটর করুন।
• রিসিভার বন্ধ করার আগে এন্ডপয়েন্ট নিষ্ক্রিয় বা মুছে দিন।