Digital Goods Orders के लिए Webhooks

संक्षिप्त उत्तर

Webhooks HTTP push notifications हैं जो supplier की system से आपके server पर order event होने पर भेजी जाती हैं। Digital goods के लिए critical events हैं: order created, order fulfilled, order failed। Code ready है या नहीं देखने के लिए बार-बार order status endpoint poll करने के बजाय, webhooks आपके server को fulfillment complete होते ही notify करते हैं। यह delivery faster बनाता है, API calls कम करता है और polling-related delays खत्म करता है।

परिभाषा: Digital goods orders के लिए webhook एक HTTP POST request है जो supplier आपके server endpoint पर तब भेजता है जब order का status बदलता है — जैसे code delivery के लिए ready हो। आपका server event receive करता है और बिना poll किए delivery process करता है।

मुख्य निष्कर्ष: Order status endpoint को poll करना small scale पर काम करता है। High volume पर, polling rate limits hit करती है और latency introduce करती है। Webhooks production-grade solution हैं: हर order change पर एक event, जैसे होता है deliver होता है।

यह Guide किसके लिए है

• Developers जो digital goods API integrate कर रहे हैं और async order handling चाहते हैं
• Store operators जिनका order fulfillment कभी-कभी delayed होता है (pending orders)
• High-volume digital goods pipeline build करने वाले

Polling vs. Webhooks

Webhook Event Types

Digital goods supplier API के लिए इन event types की उम्मीद करें:

सबसे critical event है order.fulfilled — यह code delivery के लिए trigger है।

Webhook Payload Format (Typical)

{
  "event": "order.fulfilled",
  "timestamp": "2026-05-01T14:23:11Z",
  "data": {
    "order_id": "SUP-99887",
    "reference": "ORD-12345",
    "status": "fulfilled",
    "items": [
      {
        "sku": "steam-20-usd",
        "code": "XXXXX-YYYYY-ZZZZZ",
        "pin": null
      }
    ]
  },
  "signature": "sha256=abc123..."
}

reference field हमेशा check करें — यह आपका internal order ID है, जो supplier event को आपके database से match करने देता है बिना supplier के order IDs को primary keys के रूप में store किए।

Signature Validation

Suppliers webhook payloads sign करते हैं ताकि आप verify कर सकें कि वे legitimate source से आए हैं। Validation के बिना, कोई भी आपके endpoint पर POST कर सकता है।

HMAC-SHA256 validation (सबसे common):

import hmac
import hashlib

def validate_webhook(payload_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    received = signature_header.replace('sha256=', '')
    return hmac.compare_digest(expected, received)

Rules:

• किसी भी payload को process करने से पहले validate करें
• Timing attacks रोकने के लिए constant-time comparison (hmac.compare_digest) use करें
• Signature validation fail होने पर HTTP 400 return करें (200 नहीं)
• Validation pass होने पर — event process करने से पहले — तुरंत HTTP 200 return करें

Async Processing

Webhook events को asynchronously process करें। आपका webhook endpoint supplier के timeout window (typically 3–10 seconds) के भीतर HTTP 200 return करना चाहिए। अगर आपकी event processing अधिक समय लेती है — database writes, email sends, API calls — supplier delivery को failed mark कर retry कर सकता है।

Correct architecture:

Webhook endpoint POST receive करता है
  → Signature validate करता है
  → तुरंत HTTP 200 return करता है
  → Event को queue में push करता है (Redis, SQS, DB queue table)

Background worker
  → Queue से event pull करता है
  → Process करता है: customer को code deliver करना, order status update करना

गलत: 200 return करने से पहले webhook handler के अंदर delivery process करना।

Retry Behavior

Suppliers webhook delivery retry करते हैं अगर timeout के भीतर HTTP 200 नहीं मिलता। Typical retry schedules:

• 1st retry: failure के 30 seconds बाद
• 2nd retry: 5 minutes
• 3rd retry: 30 minutes
• उसके बाद: varies (कुछ suppliers 24 hours तक retry करते हैं)

आपकी idempotency handling को retry fire होने पर same order को twice process होने से रोकना चाहिए। Order reference को idempotency key के रूप में use करें:

if order_already_delivered(reference):
    return HTTP 200  # Acknowledge, कुछ न करें

Fallback: Missing Events के लिए Polling

Webhooks fail हो सकते हैं। आपका endpoint down जा सकता है, या network issue delivery रोक सकती है। N minutes से अधिक pending status में रहने वाले orders के लिए polling fallback implement करें:

Scheduled job (हर 5 minutes):
  → Status = 'pending' और age > 5 minutes वाले सभी orders खोजें
  → हर एक के लिए: GET /orders/:id call करें
  → अगर status = fulfilled: delivery process करें
  → अगर status = failed: ops को alert करें

यह ensure करता है कि missed webhook के कारण कोई order indefinitely stuck न रहे।

Implementation Checklist

• Webhook endpoint URL supplier के पास register करें (typically API settings में)
• POST endpoint implement करें जो webhook payloads accept करे
• JSON parsing से पहले raw body read करें (raw bytes पर signature validation के लिए)
• Supplier के algorithm और shared secret से signature validation implement करें
• Validation pass होने के बाद तुरंत HTTP 200 return करें
• Event को async queue में push करें
• Queue से events process करने वाला background worker build करें
• Order reference से idempotency check implement करें
• Pending orders के लिए fallback polling implement करें
• Supplier के test event payload से test करें
• Supplier dashboard में webhook delivery failures monitor करें