Pokea webhook mara moja katika mfumo wako wa biashara
Matukio ya urejeshaji hutumia usajili wa Developer Platform na siri yake ya kutia sahihi. Callback za uthibitisho wa anwani badala yake zinaweza kuwa na siri ya kutia sahihi kwa kila ombi. Usichanganye siri hizo mbili. Jisajili kwa aina halisi za matukio zinazopatikana katika Developer Console; usidhani usajili wa wildcard unatumika.
Hakiki kabla ya kuchanganua
Alkax hutuma X-Alkax-Event-Id, X-Alkax-Timestamp (sekunde za Unix) na X-Alkax-Signature (v1= ikifuatiwa na HMAC-SHA256 ya heksadesimali yenye herufi ndogo). Data iliyotiwa sahihi ni muhuri wa muda wa UTF-8, nukta na baiti halisi ghafi za mwili wa ombi. Tumia mfuatano wa siri ya kutia sahihi kama ufunguo wa HMAC. Usiifasiri kutoka base64 au kuunda upya JSON kwanza. Kataa mihuri ya muda iliyopitwa kwa kutumia dirisha la dakika tano, mihuri ya baadaye iliyo nje ya dirisha hilo, sahihi zisizoundwa vizuri na vitambulisho vya matukio visivyolingana katika bahasha/kichwa. Sawazisha saa. Tumia ulinganishaji wa muda usiobadilika.
Fanya kipokeaji chako kipatikane kupitia endpoint ya umma ya HTTPS. Alkax haitatuma kwa anwani za loopback, binafsi, link-local au zinazoelekezwa na DNS kuwa binafsi, na uelekezaji mwingine haufuatwi. Usiweke siri za kutia sahihi katika msimbo chanzi, kumbukumbu na usanidi wa umma.
Mitego ya framework: Express lazima ichukue express.raw() kabla ya middleware ya JSON; ASP.NET lazima ihifadhi kwa muda/isome mwili wa ombi usioguswa kabla ya ubadilishaji wa modeli; Flask inapaswa kutumia request.get_data() kabla ya kuchanganua; proksi hazipaswi kubadilisha baiti za mwili. Pitisha vichwa vyote vitatu vya Alkax. Usihakiki kamwe kwa data iliyopambwa upya.
Kukubali kwa kudumu na nakala rudufu
Hakiki kwanza. Katika muamala mmoja wa hifadhidata, ingiza utambulisho wa kipekee wa mazingira na tukio pamoja na hash ya mwili ghafi na urekodi kitendo cha biashara au uweke kazi ya kudumu kwenye foleni. Kamilisha muamala kabla ya kurudisha 2xx. Mfumo ukianguka baada ya muamala lakini kabla ya jibu, utapata nakala rudufu: rudisha 2xx bila kutekeleza kitendo tena ikiwa hash inafanana kabisa pekee. Utambulisho uleule wa tukio wenye hash tofauti ni hitilafu ya uadilifu wa data na haupaswi kusababisha athari zozote. Pata hali rasmi ya sasa kwa ufunguo wa mazingira yako kabla ya kufanya maamuzi yanayotegemea mpangilio. Mpangilio wa kuwasilisha haujahakikishwa. Hifadhi rekodi za kuondoa urudiaji kwa angalau muda unaounga mkono urudiaji wa matukio.
Usiite huduma ya nje ya kurejesha fedha ndani ya mzunguko wa majaribio usiolindwa. Tumia outbox yako ya miamala na mkataba wa idempotency. return.received ya Alkax ni kupokea mzigo kimwili, si idhini ya kurejesha fedha.
Sera ya kuwasilisha
Watumaji wote wawili wa kisasa wa webhook hutumia muda wa kusubiri wa sekunde kumi na hadi majaribio nane ya kiotomatiki. Usajili wa mradi hutumia vipindi vya dakika 2, 4, 8, 16, 32, 64 na 128. Callback za kila uthibitisho hutumia takriban dakika 1, 2, 4, 8, 16, 32 na 64, zikiwa na tofauti ya nasibu. Ratiba hizi ni za watumaji tofauti. Majibu yasiyofanikiwa ya 4xx ni ya mwisho isipokuwa 408, 425 na 429; 5xx na hitilafu za usafirishaji hujaribiwa tena. Rudisha 503 kwa kushindwa kwa muda kwa hifadhi na 2xx kwa nakala rudufu zilizokubaliwa kwa kudumu. Usirudishe 200 kabla ya uhifadhi kufanikiwa. Sahihi mbaya za kudumu zinahitaji kurekebisha siri/ushughulikiaji wa mwili kabla ya kurudia tukio, si kuwasilisha mara nyingi bila uchunguzi.
Katika Developer Console, kagua historia ya uwasilishaji ya usajili, sahihisha chanzo na uchague Replay (Rudia). Urudiaji huhifadhi kitambulisho na data ya tukio, lakini hutia sahihi kwa muhuri mpya wa muda. Kwa hiyo, kuondoa urudiaji lazima kutegemee kitambulisho cha tukio, si sahihi au muhuri wa muda.
Hifadhi siri za usajili katika kidhibiti cha siri. Kubadilisha kitambulisho hakubadilishi siri za webhook. Kubadilisha siri ya usajili, unda usajili mbadala, kubali siri zote mbili wakati wa mpito, ondoa usajili wa zamani na upatanishe uwasilishaji unaosubiri.
Ushughulikiaji wa data
Bahasha ya urejeshaji ina eventId, type, occurredAt na data. Data ina vitambulisho vya urejeshaji/shehena ya awali, namba ya ufuatiliaji, hali ya idhini/usafirishaji, sababu/aina na muda wa tukio. Chukulia merchantReference kuwa data inayotolewa na mfanyabiashara ambayo huenda ni nyeti. Usiweke bahasha nzima kwenye kumbukumbu. Tukio hili la umma la uunganishaji halina uwezo wa ufikiaji wa mpokeaji, anwani sahihi au picha za ushahidi.
Alkax -> signed HTTPS webhook -> verify raw bytes -> durable inbox/work -> 2xx
|
+-> transient failure -> safe retry
Mikataba ya uthibitisho na urejeshaji
API ya HTTP ya uthibitisho, callback za awali za kila uthibitisho, callback zenye matoleo za kila uthibitisho na usajili wa jumla wa mradi zina miundo tofauti:
| Njia | Sehemu na hali |
|---|---|
| Jibu la HTTP la uthibitisho lenye uthibitishaji wa ufikiaji | Sehemu za camelCase, hali ya maandishi; nakala binafsi na deliveryInstructions; sehemu za matumizi ya mara moja ni null katika usomaji wa kawaida |
Callback ya kila uthibitisho v1 kwa chaguo-msingi | Sehemu za juu eventId, type, occurredAt, request; sehemu za ndani za PascalCase na hali ya namba |
Callback ya kila uthibitisho v2 iliyochaguliwa wazi | Sehemu za juu schemaVersion, eventId, type, occurredAt, request; kitambulisho, rejea, hali ya maandishi na muda wa kuisha wa ombi pekee katika camelCase |
| Usajili wa mradi | Sehemu za juu eventId, type, occurredAt, data; data ya uthibitisho ni id, status ya namba na expiresAt pekee |
Kiambishi v1= cha kichwa cha sahihi kinamaanisha utaratibu wa HMAC; hakichagui muundo wa JSON. Chagua sehemu ya hiari callbackSchemaVersion unapounda uthibitisho mpya. Baiti za tukio lililo kwenye foleni na muundo uliochaguliwa hubaki vilevile linaporudiwa. Kurudia mwenyewe callback ya kila uthibitisho huhifadhi jumla ya majaribio yaliyofanyika; hakuhakikishi majaribio manane mapya.
Ili kurejesha baada ya kupotea kwa jibu, tengeneza na usimbe callbackSigningSecret ya hiari katika hifadhi ya kudumu kabla ya kuunda uthibitisho. Lazima iwe na herufi 64 ndogo za heksadesimali zinazotokana na baiti 32 za nasibu, pamoja na callbackUrl iliyosanidiwa. HMAC hutumia maandishi ya siri ya UTF-8. Alkax hairudishi kamwe siri iliyotolewa na mwitaji. Ikiachwa, Alkax hutengeneza webhookSigningSecret na kuirudisha katika jibu la kwanza la kuunda pekee. Hakuna endpoint ya kubadilisha au kutoa tena siri.
Jaribio linalofanana kabisa la kuunda hurudisha ombi la awali, huku recipientUrl na sehemu za siri za matumizi ya mara moja zikiwa null, hata baada ya muda wa kiungo cha awali. Hifadhi data na ufunguo uleule kabisa na utumie rejea mpya fiche kwa jaribio jipya. Hakiki utambulisho wa tukio katika kichwa na mwili, lihusishe na jaribio la sasa la ndani, hifadhi mazingira na kitambulisho cha tukio pamoja na hash ya mwili, kisha patanisha kupitia GET ya msingi yenye uthibitishaji. Kuisha kwa muda wa kiungo hakubatilishi nakala zilizokamilika; muda wa ridhaa na ufichuaji wa taarifa ni jukumu la programu inayotumia huduma.
Majibu ya majaribio na historia ya uwasilishaji wa mradi huonesha metadata za uwasilishaji zilizoidhinishwa wazi pekee. Data ghafi, sehemu za majibu ya kipokeaji na sababu za hitilafu za maandishi huru huondolewa kwa kila jukumu la mradi. Matukio ya zamani ya uthibitisho wa mradi yasiyo salama huondolewa kwenye uwasilishaji kabla ya kutumwa na kurudiwa kwake mwenyewe hukataliwa; siri za zamani zilizohifadhiwa bado zinahitaji hatua za marekebisho ya uendeshaji zenye mipaka maalumu. Hili halibadilishi viungo vya ufikiaji au siri zilizofichuliwa awali.
Arifa za uthibitisho za Sandbox huhifadhiwa kwenye hifadhi ya majaribio badala ya kutumwa kwenye visanduku vya wapokeaji halisi, na operesheni zote za uthibitisho hufungwa kwa mradi na mazingira. Weka toleo linalolingana la mtoa huduma kabla ya kutumia nyongeza hizi. Tazama mkataba wa callback unaoweza kurejeshwa kwa mfano kamili wa data na masharti yaliyobaki ya kutolewa. Kiolesura binafsi cha VolXpr kilichowekwa kwenye huduma, mchakato wa ruhusa unaohifadhiwa kwa kudumu na kazi kamili ya ushindani wa mabadiliko ya mzunguko wa maisha hubaki tofauti.