ऑफ-रैंप lifecycle के लिए HMAC-signed webhooks।
जब आपके प्रोडक्ट को asynchronous lifecycle state चाहिए, तब webhook endpoints register करें और हर delivery verify करें। signature timestamp को बिलकुल सटीक raw body से बाँधता है ताकि आप छेड़े गए या replay किए गए payloads को रिजेक्ट कर सकें।
Lifecycle events
| Event | मतलब |
|---|---|
| deposit.created | Base पर एक seller deposit बनाया गया |
| deposit.partially_filled | एक deposit आंशिक रूप से fill हुआ |
| deposit.filled | एक deposit पूरी तरह fill हुआ |
| deposit.closed | एक seller ने बची हुई बैलेंस close या withdraw की |
| otc.taken | एक private OTC deposit को approved buyer ने लिया |
हर delivery verify करें
- 1X-Usdctofiat-Signature header को t=<unix>,v1=<hex> फ़ॉर्म में पढ़ें।
- 2raw, बिना-parse किए body का इस्तेमाल करते हुए signed payload को string timestamp.rawBody के रूप में बनाएँ।
- 3उस payload पर अपने endpoint secret के साथ HMAC-SHA256 compute करें।
- 4event पर भरोसा करने से पहले constant time में v1 hex वैल्यू से तुलना करें।
- 5वैकल्पिक रूप से उन deliveries को रिजेक्ट करें जिनका timestamp आपकी चुनी हुई window से पुराना हो।
Replay सुरक्षा आपकी पसंद है
starters repo में reference receiver replays से बचाव के लिए 5 मिनट से पुराने timestamps को stale मानता है। वह window sender नहीं, बल्कि आपका verifier लागू करता है, इसलिए आप इसे अपनी latency और retry सहनशीलता के अनुसार कसी या ढीली कर सकते हैं।
चूँकि signature timestamp.rawBody को कवर करता है, JSON को HMAC जाँच पास होने के बाद ही parse करें। raw bytes के बजाय parse किए गए object को verify करना signature verification को सूक्ष्म रूप से गलत करने का सबसे आम तरीका है।
Register और ऑपरेट करें
- अपनी Peerlytics API key के साथ endpoints register करें; एक key offramp और Peerlytics दोनों सरफेस को authenticate करती है।
- जो endpoints लगातार बार-बार delivery failures में पड़ते हैं, उन्हें तब तक disable किया जा सकता है जब तक आप उन्हें ठीक न कर लें।
- starters repo receiver को एक known-good HMAC verification reference के रूप में इस्तेमाल करें।
- webhooks को state hints मानें; जब मायने रखे, तब deposits() के साथ onchain सच्चाई से reconcile करें।
Keep exploring
Common questions
USDCtoFiat webhooks कैसे signed होते हैं?
हर delivery में X-Usdctofiat-Signature: t=<unix>,v1=<hex> होता है, जो string timestamp.rawBody पर HMAC-SHA256 है। event पर भरोसा करने से पहले raw body पर अपने endpoint secret के साथ HMAC दोबारा compute करें और constant time में तुलना करें।
मैं replay किए गए webhooks को कैसे रोकूँ?
उन deliveries को रिजेक्ट करें जिनका signed timestamp आपकी चुनी हुई window से पुराना हो। reference receiver 5 मिनट इस्तेमाल करता है। sender कोई window लागू नहीं करता, इसलिए यह आपके verifier की ज़िम्मेदारी है।
क्या webhooks के लिए मुझे API key चाहिए?
हाँ। deposits बनाना permissionless है, लेकिन webhook endpoints register करने में एक Peerlytics API key लगती है। वही key Peerlytics API को भी authenticate करती है।