मुख्य सामग्री पर जाएं
Asynchronous changes पर प्रतिक्रिया करने के लिए webhooks का उपयोग करें। Delivery कम से कम एक बार है, इसलिए duplicate, delayed, और out-of-order events सामान्य हैं।

केवल आवश्यक events register करें

एक endpoint को POST /v3/webhooks के साथ बनाएँ। केवल दस्तावेज़ीकृत events की सदस्यता लें जो आपके integration को drive करते हैं। यह उदाहरण transfer.state_changed का उपयोग करता है।
Create webhook endpoint
Response data.id को WEBHOOK_ID के रूप में संग्रहीत करें। जिस API key के पास webhooks:write है, उसके साथ GET /v3/webhooks/portal से एक portal URL request करें, इस endpoint की signing secret प्राप्त करें, और इसे अपनी API key से अलग एक secret manager में संग्रहीत करें। Portal URL अपने आप में access देता है और एक घंटे बाद expire हो जाता है, इसलिए हर बार नया URL request करें और इसे store या share न करें। Portal v3 events को resource के अनुसार group करता है: Customers, Capabilities, Accounts, Recipients, Transfers, और API। प्रत्येक event अपना payload schema और एक example दिखाता है। Legacy events deprecated के रूप में mark किए जाते हैं और एक अलग Legacy group में list किए जाते हैं। यदि आपका endpoint पहले से किसी legacy event को subscribe करता है, तो उसे वह event मिलता रहेगा। नए subscriptions के लिए v3 event names चुनें।

किसी endpoint के events बदलें

GET /v3/webhooks/{webhookId} के साथ एक endpoint पढ़ें। Response का events shape GET /v3/webhooks जैसा ही होता है। इसमें signing secret कभी शामिल नहीं होती। Reads के लिए webhooks:read आवश्यक है और अज्ञात endpoint ID के लिए ये 404 not_found लौटाते हैं। Endpoint को PATCH /v3/webhooks/{webhookId} के साथ update करें। एक Idempotency-Key header भेजें। Updates के लिए webhooks:write आवश्यक है।
  • वर्तमान URL बनाए रखने के लिए केवल events भेजें।
  • वर्तमान event selection बनाए रखने के लिए केवल url भेजें।
  • events पूरे selection को replace करता है। पहले endpoint पढ़ें और हर वह event शामिल करें जिसकी आपको अभी भी आवश्यकता है।
  • नए subscriptions को v3 event names का उपयोग करना होगा।
  • यदि endpoint पहले से किसी legacy event name को subscribe करता है, तो आप उसे बनाए रख सकते हैं। नया legacy name जोड़ने पर 400 validation_error लौटता है।
यह body URL को बनाए रखती है और selection को replace करती है:
Request body

Parsing से पहले verify करें

Swipelux नए webhook integrations को Svix के माध्यम से deliver करता है। अपनी endpoint signing secret और इन headers के साथ raw request body को verify करें:
  • svix-id
  • svix-timestamp
  • svix-signature
Verification सफल होने से पहले JSON parse न करें या side effects का कारण न बनें।
Verify signature
अनुपस्थित या अमान्य signatures वाले requests को अस्वीकार करें। Verification पूरा होने तक raw body उपलब्ध रखें।

Persist, acknowledge, फिर process

Envelope id पर एक uniqueness constraint लगाएँ। Verified envelope को persist करें, तुरंत 2xx लौटाएँ, फिर इसे asynchronously process करें। यदि event ID पहले से मौजूद है, तो पूर्ण किए गए side effects को दोहराए बिना delivery को acknowledge करें। अपनी retry queue के माध्यम से pending या failed local work को फिर से शुरू करें। Envelope attempt field को deduplication key या transport retry counter के रूप में उपयोग न करें।

वर्तमान state पुन: प्राप्त करें

Webhook order एक authoritative resource history नहीं है। Object का पता लगाने के लिए resource.type और resource.id का उपयोग करें, फिर अपने system को update करने से पहले इसकी वर्तमान state प्राप्त करें। एक transfer event के लिए, GET /v3/transfers/{transferId} को call करें:
Refetch transfer
वर्तमान API response से customer-visible status और downstream actions को drive करें। Side effects को इस तरह design करें कि यदि दो workers संबंधित events को अलग order में process करें तो सुरक्षित रहें।

Deliveries recover करें

Delivery logs खोलने के लिए GET /v3/webhooks/portal का उपयोग करें। webhooks:write के साथ, आप failed deliveries retry भी कर सकते हैं या manual replay शुरू कर सकते हैं। केवल webhooks:read वाली key एक ऐसा portal खोलती है जो deliveries दिखाता है, लेकिन उन्हें retry या replay नहीं कर सकता और signing secrets नहीं दिखा सकता। प्रत्येक replay को उसी signature verification और durable inbox से गुजरना होगा। Downtime के बाद recover करने के लिए, प्रभावित window को replay करें और प्रत्येक संदर्भित resource को पुन: प्राप्त करें। पूर्ण किए गए event IDs no-ops रहते हैं; अपूर्ण records asynchronously फिर से शुरू होते हैं। आगे, sandbox में duplicate और out-of-order deliveries को verify करें, फिर Go live checklist पूरी करें।