सेटअप
IDCloud दो webhook modalities को support करता है, यह इस बात पर निर्भर करता है कि आप कैसे integrate करते हैं:
- Via Portal — Web और SDK integrations के लिए। IDCloud portal में सीधे self-service कॉन्फ़िगरेशन।
- By client — Check orchestration capability (एक asynchronous flow) का उपयोग करने वाले API integrations के लिए। Unico टीम द्वारा कॉन्फ़िगर किया जाता है। केवल ब्राज़ील में उपलब्ध।
- Via Portal (Web & SDK)
- By client (API — केवल ब्राज़ील)
अपना webhook endpoint पंजीकृत या update करने के लिए, IDCloud portal में जाएं और Settings > Webhook पर navigate करें।
आवश्यक जानकारी
| Field | विवरण |
|---|---|
| Notification URL | Endpoint जिसे Unico event notifications deliver करने के लिए call करेगा। HTTPS के माध्यम से पहुँचने योग्य होना चाहिए। |
| Authentication type | Unico आपके endpoint के विरुद्ध कैसे authenticate करता है। नीचे विकल्प देखें। |
| Retry settings | अधिकतम attempts की संख्या और attempts के बीच अंतराल (exponential backoff लागू किया जाता है)। |
| Concurrency limit | अधिकतम simultaneous in-flight deliveries की संख्या (अधिकतम: 500)। |
| Timeout | Endpoint की response के लिए अधिकतम प्रतीक्षा समय, सेकंड में। |
| Status to notify | Process states का वह समूह जो एक notification trigger करते हैं। वर्तमान में PROCESS_STATE_FINISHED पर fixed है; इस समय configurable न हीं है। |
Authentication methods
OAuth2
प्रदान करें:
- Webhook
endpoint - OAuth2 provider
URL - OAuth2 provider
ClientId - OAuth2 provider
Secret
Unico client credentials का उपयोग करके provider URL से access token का अनुरोध करेगा और इसे आपके endpoint पर Bearer token के रूप में forward करेगा।
Basic Authorization
user:pass format में credentials प्रदान करें। Unico उन्हें Base64 में encode करता है और प्रत्येक webhook call पर Authorization: Basic <encoded> header में भेजता है।
API Key
दो formats समर्थित हैं। String को पहले colon पर split किया जाता है:
header:value— एक custom header name set करता है। उदाहरण:X-API-Key:abc123→X-API-Key: abc123Authorization:Bearer abc123→Authorization: Bearer abc123
- केवल
value(बिना colon के) — value कोAuthorizationheader के रूप में बिना किसी scheme prefix के भेजा जाता है। उदाहरण:abc123→Authorization: abc123।
Bearer scheme की आवश्यकता होने पर header:value format का उपयोग करें (जैसे, Authorization:Bearer <token>); value-only format raw value को बिना prefix के भेजता है।
कोई authentication नहीं
कोई credentials नहीं भेजे जाते। केवल development environments के लिए अनुशंसित — production endpoints को हमेशा authentication की आवश्यकता होनी चाहिए।
Process states जो notifications trigger करते हैं
वर्तमान में, Unico एक notification भेजता है जब भी कोई process transition करता है:
| State | विवरण |
|---|---|
PROCESS_STATE_FINISHED | Process समाप्त — terminal state, परिणाम चाहे जो भी हो। |
Platform द्वारा notify किए जाने वाले states का set भविष्य में बदल सकता है। जिन states पर आपका endpoint react करता है उन्हें configurable बनाएं, ताकि नया state जोड़ने के लिए आपकी service को फिर से deploy न करना पड़े।
Request format
Webhook deliveries आपके endpoint पर POST requests हैं। Body में process identifier और current state शामिल हैं।
{
"processId": "8263a268-5388-492a-bca2-28e1ff4a69f0",
"state": "PROCESS_STATE_FINISHED",
"flow": "id"
}
lastEvent और lastEventDescriptionये दोनों fields payload में केवल तब दिखाई देते हैं जब result = expired — अर्थात, जब user ने journey पूरी करने से पहले process expire हो गई हो। ये सामान्य completion payloads में अनुपस्थित होते हैं। पूर्ण schema और संभावित lastEvent values की सूची के लिए Event types देखें।
Expected response
आपका endpoint synchronously respond करना होगा:
- सफलता:
200–299range में कोई भी HTTP status। - विफलता: कोई अन्य status। Unico configured अधिकतम attempts तक या
2xxप्राप्त होने तक exponential backoff के साथ retry करेगा।
Webhook को जल्दी acknowledge करें (अपने configured timeout के भीतर) और अपनी तरफ asynchronously payload process करें। Webhook handler के अंदर long-running processing timeouts और अनावश्यक retries की संभावना बढ़ाती है।
Idempotency और retry handling मार्गदर्शन के लिए, Security देखें।
By-client webhook केवल ब्राज़ील में उन API integrations के लिए उपलब्ध है जो Check orchestration capability का उपयोग करते हैं — एक asynchronous flow जहाँ process का परिणाम synchronous API response के बजाय webhook के माध्यम से deliver किया जाता है।
अपना endpoint पंजीकृत या update करने के लिए, अपनी CS / Onboarding टीम से संपर्क करें।
आवश्यक जानकारी
| Field | विवरण |
|---|---|
| Notification URL | Endpoint जिसे आपका system status updates प्राप्त करने के लिए expose करता है। HTTPS के माध्यम से पहुँचने योग्य होना चाहिए। |
| Authentication type | Unico आपके endpoint के विरुद्ध कैसे authenticate करता है। नीचे विकल्प देखें। |
| Retry settings | अधिकतम attempts की संख्या और attempts के बीच अंतराल (exponential backoff लागू किया जाता है)। |
| Concurrency limit | अधिकतम simultaneous in-flight deliveries की संख्या (अधिकतम: 500)। |
| Timeout | Endpoint की response के लिए अधिकतम प्रतीक्षा समय, सेकंड में। |
Authentication methods
OAuth2
प्रदान करें:
- Webhook
endpoint - OAuth2 provider
URL - OAuth2 provider
ClientId - OAuth2 provider
Secret
Unico client credentials का उपयोग करके provider URL से access token का अनुरोध करेगा और इसे आपके endpoint पर Bearer token के रूप में forward करेगा।
Basic Authorization
user:pass format में credentials प्रदान करें। Unico उन्हें Base64 में encode करता है और प्रत्येक webhook call पर Authorization: Basic <encoded> header में भेजता है।
API Key
दो formats समर्थित हैं। String को पहले colon पर split किया जाता है:
header:value— एक custom header name set करता है। उदाहरण:X-API-Key:abc123→X-API-Key: abc123Authorization:Bearer abc123→Authorization: Bearer abc123
- केवल
value(बिना colon के) — value कोAuthorizationheader के रूप में बिना किसी scheme prefix के भेजा जाता है। उदाहरण:abc123→Authorization: abc123।
Bearer scheme की आवश्यकता होने पर header:value format का उपयोग करें (जैसे, Authorization:Bearer <token>); value-only format raw value को बिना prefix के भेजता है।
कोई authentication नहीं
कोई credentials नहीं भेजे जाते। केवल development environments के लिए अनुशंसित — production endpoints को हमेशा authentication की आवश्यकता होनी चाहिए।
Status codes
By-client webhook numeric status codes का उपयोग करता है:
| Code | विवरण |
|---|---|
2 | Divergence — identity check में divergence के साथ process पूरी हुई। |
3 | Completed — process सफलतापूर्वक पूरी हुई। |
5 | Error — किसी error के कारण process समाप्त हुई। |
Request format
Webhook deliveries आपके endpoint पर POST requests हैं। Body में transaction identifier और numeric status code शामिल हैं।
{
"id": "8263a268-5388-492a-bca2-28e1ff4a69f0",
"status": 3
}
Expected response
आपका endpoint synchronously respond करना होगा:
- सफलता:
200–299range में कोई भी HTTP status। - विफलता: कोई अन्य status। Unico configured अधिकतम attempts तक या
2xxप्राप्त होने तक exponential backoff के साथ retry करेगा।
Webhook को जल्दी acknowledge करें (अपने configured timeout के भीतर) और अपनी तरफ asynchronously payload process करें। Webhook handler के अंदर long-running processing timeouts और अनावश्यक retries की संभावना बढ़ाती है।
Platform at-least-once delivery की गारंटी देता है — एक ही notification एक से अधिक बार आ सकती है। Duplicates को safely handle करने के लिए id field का उपयोग करके अपनी तरफ idempotency implement करें।
Idempotency और retry handling मार्गदर्शन के लिए, Security देखें।