इसे छोड़कर कंटेंट पर जाएं
MirApi Docs

वेबहुक कॉलबैक कतार

MirApi का async वेबहुक मोड API कॉल को एक बैकग्राउंड वर्कर पूल में भेज देता है और आपके कॉलर को तुरंत 202 Accepted लौटाता है। जब अपस्ट्रीम जवाब देता है, तो MirApi परिणाम को आपके कॉलबैक URL पर POST करता है। वर्कर पूर्ण रिट्री लॉजिक का समर्थन करता है और यदि अपस्ट्रीम अस्थायी रूप से अनुपलब्ध है तो घंटों तक पुनः प्रयास करता रहता है।

यह कैसे काम करता है

Section titled “यह कैसे काम करता है”
Your App                  MirApi                    Upstream API
    |                        |                            |
    |──POST (+ X-Webhook)───→|                            |
    |←──202 Accepted─────────|                            |
    |   {"job_id": "..."}    |                            |
    |                        |──push to Redis queue──→   |
    |                        |                       (async worker)
    |                        |←──upstream response────────|
    |←──POST /your/webhook───|                            |
    |   (full response)      |

async मोड क्यों उपयोग करें?

  • आपके ऐप का रिक्वेस्ट थ्रेड तुरंत मुक्त हो जाता है — धीमे अपस्ट्रीम का इंतज़ार नहीं करना पड़ता
  • वर्कर ज़रूरत पड़ने पर घंटों तक रिट्री करता है, अस्थायी आउटेज को पारदर्शी तरीके से संभालता है
  • डुप्लीकेट जॉब सबमिशन रोकने के लिए X-Proxy-Idempotency-Key के साथ जोड़ें
  • उचित शेड्यूलिंग के लिए जॉब सब्सक्रिप्शन टियर (business, developer, free) के अनुसार कतारबद्ध होती हैं

बुनियादी उपयोग

Section titled “बुनियादी उपयोग”
Terminal window
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.stripe.com/v1/charges" \
  -H "X-Identity-Key: Bearer sk_live_..." \
  -H "X-Webhook-Callback: https://your-app.com/api/webhooks/payments" \
  -H "X-Proxy-Idempotency-Key: order_789_pay_attempt_1" \
  -H "Content-Type: application/json" \
  -d '{"amount": 9900, "currency": "usd", "source": "tok_visa"}'

तत्काल रिस्पॉन्स:

HTTP/1.1 202 Accepted
Content-Type: application/json


{
  "status": "Accepted",
  "job_id": "8fd2a023-df21-4ea7-8b01-5d9f0f9b36ea"
}

आवश्यक हेडर

Section titled “आवश्यक हेडर”
हेडरआवश्यकविवरण
X-Webhook-Callbackहाँआपका एंडपॉइंट URL जो जॉब पूरी होने पर POST प्राप्त करता है

आपके कॉलबैक को क्या मिलता है

Section titled “आपके कॉलबैक को क्या मिलता है”

जब बैकग्राउंड वर्कर अपस्ट्रीम कॉल पूरी करता है, तो वह आपके X-Webhook-Callback URL पर POST भेजता है। बॉडी में अपस्ट्रीम API का raw रिस्पॉन्स बॉडी होती है — ठीक वही जो आपको सिंक्रोनस कॉल में मिलती।

सफलता पर, आपके कॉलबैक को अपस्ट्रीम रिस्पॉन्स बॉडी मिलती है:

POST https://your-app.com/api/webhooks/payments
Content-Type: application/json


{
  "id": "ch_3Pz9...",
  "status": "succeeded",
  "amount": 9900,
  "currency": "usd"
}

विफलता पर (सभी रिट्री समाप्त), आपके कॉलबैक को एक त्रुटि पेलोड मिलता है:

{
  "error": "upstream_failed",
  "job_id": "8fd2a023-df21-4ea7-8b01-5d9f0f9b36ea",
  "status_code": 503,
  "message": "All retry attempts failed for https://api.stripe.com/v1/charges"
}

रिट्री लॉजिक के साथ संयोजन

Section titled “रिट्री लॉजिक के साथ संयोजन”

async वर्कर वही रिट्री इंजन उपयोग करता है जो सिंक्रोनस रिक्वेस्ट के लिए होता है। रिट्री व्यवहार नियंत्रित करने के लिए X-Retry-Count और X-Retry-Delay का उपयोग करें:

Terminal window
# 5 रिट्री के साथ पेमेंट, 1 सेकंड की देरी से शुरू
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.stripe.com/v1/charges" \
  -H "X-Identity-Key: Bearer sk_live_..." \
  -H "X-Webhook-Callback: https://your-app.com/api/webhooks/payments" \
  -H "X-Proxy-Idempotency-Key: order_789_pay_1" \
  -H "X-Retry-Count: 5" \
  -H "X-Retry-Delay: 1s" \
  -H "X-Proxy-Timeout: 10s" \
  -H "X-Attempt-Timeout: 2s" \
  -H "Content-Type: application/json" \
  -d '{"amount": 9900, "currency": "usd", "source": "tok_visa"}'

कैस्केड रूट्स के साथ संयोजन

Section titled “कैस्केड रूट्स के साथ संयोजन”

पूरी कैस्केड रणनीति को असिंक्रोनस रूप से चलाने के लिए X-Route-Key को X-Webhook-Callback के साथ उपयोग करें:

Terminal window
# कई प्रोवाइडरों में async AI रिक्वेस्ट
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Route-Key: ai-providers" \
  -H "X-Webhook-Callback: https://your-app.com/ai-results" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Summarize this document: ..."}'
# तुरंत 202 लौटाता है
# वर्कर openai → anthropic → groq को आज़माता है (रूट कॉन्फ़िग के अनुसार)
# पहला सफल रिस्पॉन्स आपके वेबहुक पर POST करता है

async जॉब के लिए आइडेम्पोटेंसी

Section titled “async जॉब के लिए आइडेम्पोटेंसी”

असिंक्रोनस रूप से पेमेंट प्रोसेस करते समय हमेशा X-Proxy-Idempotency-Key प्रदान करें। यदि 60 सेकंड के भीतर वही कुंजी दोबारा आती है (जैसे क्लाइंट रिट्री के कारण), तो MirApi उसी job_id के साथ वही 202 रिस्पॉन्स लौटाता है — कोई डुप्लीकेट जॉब कतार में नहीं जाती।

Terminal window
# पहली रिक्वेस्ट → जॉब बनाती है, job_id लौटाती है
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.stripe.com/v1/charges" \
  -H "X-Webhook-Callback: https://your-app.com/webhook" \
  -H "X-Proxy-Idempotency-Key: charge_order_123" \
  -d '{"amount": 5000, "currency": "usd"}'
# → 202: {"status": "Accepted", "job_id": "abc-123"}


# 60 सेकंड के भीतर वही कुंजी दोबारा → कोई नई जॉब नहीं
# → 202: {"status": "Accepted", "job_id": "abc-123"}  (वही job_id, कैश्ड रिस्पॉन्स)

व्यावहारिक उदाहरण: ई-कॉमर्स पेमेंट फ्लो

Section titled “व्यावहारिक उदाहरण: ई-कॉमर्स पेमेंट फ्लो”
Terminal window
# चरण 1: async रूप से चार्ज सबमिट करें
curl -X POST https://proxy.mirapi.io/ \
  -H "X-MirApi-Key: $MIRAPI_KEY" \
  -H "X-Target-URL: https://api.stripe.com/v1/charges" \
  -H "X-Identity-Key: Bearer sk_live_..." \
  -H "X-Webhook-Callback: https://myshop.com/api/payments/confirm" \
  -H "X-Proxy-Idempotency-Key: order_456_cart_789_attempt_1" \
  -H "X-Retry-Count: 3" \
  -H "X-Proxy-Timeout: 15s" \
  -H "X-Attempt-Timeout: 3s" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "currency": "usd",
    "source": "tok_visa",
    "description": "Order #456"
  }'


# चरण 2: आपका ऐप तुरंत उपयोगकर्ता को जवाब देता है ("पेमेंट प्रोसेस हो रही है...")


# चरण 4: MirApi वर्कर Stripe को कॉल करता है, ज़रूरत पड़ने पर रिट्री करता है
# चरण 5: Stripe सफल → MirApi https://myshop.com/api/payments/confirm पर POST करता है
# चरण 6: आपका हैंडलर ऑर्डर को paid के रूप में चिह्नित करता है

थर्ड-पार्टी वेबहुक प्रोड्यूसर के साथ async मोड (Shopify, GitHub, Stripe)

Section titled “थर्ड-पार्टी वेबहुक प्रोड्यूसर के साथ async मोड (Shopify, GitHub, Stripe)”

कई प्लेटफ़ॉर्म जो वेबहुक फायर करते हैं — Shopify Admin, GitHub Actions, Stripe — केवल आपको एक डेस्टिनेशन URL दर्ज करने देते हैं। वे कस्टम HTTP हेडर की अनुमति नहीं देते।

ऐसे परिदृश्यों के लिए, MirApi हेडर की जगह सभी कॉन्फ़िगरेशन को URL क्वेरी पैरामीटर के रूप में पास करने का समर्थन करता है। उदाहरण के लिए, Shopify को 10 रिट्री के साथ ऑर्डर कतारबद्ध करने के लिए कॉन्फ़िगर करने हेतु:

https://proxy.mirapi.io/v1/webhook?mirapi_key=your_api_key&callback=https%3A%2F%2Fmy-erp.com%2Fapi%2Forders&retries=10&delay=1s&timeout=5s

पूर्ण गाइड, मैपिंग तालिका, और चरण-दर-चरण Shopify इंटीग्रेशन यहाँ देखें: URL क्वेरी पैरामीटर कॉन्फ़िगरेशन

अतिरिक्त संसाधन (Additional Resources)

Section titled “अतिरिक्त संसाधन (Additional Resources)”