केवल आवश्यक events register करें
एक endpoint कोPOST /v3/webhooks के साथ बनाएँ। केवल दस्तावेज़ीकृत events की सदस्यता लें जो आपके integration को drive करते हैं। यह उदाहरण transfer.state_changed का उपयोग करता है।
Create webhook endpoint
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लौटता है।
Request body
Parsing से पहले verify करें
Swipelux नए webhook integrations को Svix के माध्यम से deliver करता है। अपनी endpoint signing secret और इन headers के साथ raw request body को verify करें:svix-idsvix-timestampsvix-signature
Verify signature
Persist, acknowledge, फिर process
Envelopeid पर एक 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
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 पूरी करें।