FoxReload Webhooks Integration — रियल-टाइम ऑर्डर अपडेट्स

जब आप FoxReload API पर ऑर्डर बनाते हैं, डिलीवरी सिंक्रोनस नहीं है — कोड्स backend से 1–60 सेकंड में आते हैं। पोलिंग से बेहतर है webhooks का इस्तेमाल: हम आपके endpoint पर POST करते हैं हर बार जब ऑर्डर का स्टेटस बदलता है।

Webhook setup

1. डैशबोर्ड में: Settings → Webhooks → Add Endpoint.
2. URL डालें: https://yourshop.com/api/foxreload-webhook। यह HTTPS होना चाहिए (HTTP swhole reject किया जाएगा)।
3. Events चुनें: order.created, order.delivered, order.failed, order.refunded। हम सभी डिफ़ॉल्ट से चुनते हैं।
4. Secret key save करें — यह HMAC signature के लिए चाहिए।

Payload structure

हर webhook POST में JSON body आता है:

{
  "event": "order.delivered",
  "order_id": "ord_abc123",
  "sku_id": "psn-tr-100",
  "wholesale_cost_usd": "8.45",
  "delivered_at": "2026-05-18T14:32:11Z",
  "delivery_data": {
    "code": "XXXX-YYYY-ZZZZ-AAAA",
    "type": "redeem_code"
  }
}

HMAC-SHA256 signature verification

हर POST में हम X-FoxReload-Signature हेडर भेजते हैं। आपको इसे verify करना ज़रूरी है — वरना कोई भी आपके endpoint पर fake events भेज सकता है।

import crypto from 'crypto';

function verifySignature(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

ज़रूरी: rawBody को parse करने से पहले verify करें — JSON.parse के बाद byte-exact नहीं रहेगा।

Idempotency और retry logic

FoxReload कोई भी webhook एक से अधिक बार भेज सकता है (network glitch, server restart)। हर event में unique event_id होती है।

आपकी responsibility:

• event_id को database में store करें।
• जब वही event_id दूसरी बार आए — skip करें।

Retry behaviour

• अगर आपका endpoint HTTP 2xx नहीं देता — हम retry करते हैं।
• Backoff: 30s, 5min, 30min, 2h, 6h, 24h (कुल 6 attempts)।
• 24 घंटे के बाद webhook drop हो जाता है — हम email alert भेजते हैं।

Best practices

टेस्ट कैसे करें

Production में जाने से पहले:

1. ngrok या localtunnel से local endpoint expose करें।
2. डैशबोर्ड में Test Webhook बटन से sample event भेजें।
3. Signature verification verify करें।

FoxReload Webhooks के साथ आप कस्टमर को तुरंत ऑर्डर delivery confirm कर सकते हैं — manual polling के बजाय, जो latency और सर्वर लोड दोनों कम करता है।