Mis on webhook (sündmuse automaatteade)?

Webhook on teade, mille saatja otsustab

Webhook on HTTP-päring, mille üks süsteem saadab teisele automaatselt sündmuse toimumise hetkel. Sina annad teenusepakkujale aadressi, nemad saadavad sinna sündmuse andmed. Stripe'i dokumentatsioon sõnastab selle nii: registreerid HTTPS-aadressi ja Stripe saadab sinna reaalajas andmeid, kui sinu kontol midagi juhtub, JSON-vormingus.

Oluline on see, kes päringu algatab. Tavalise API-puhul küsib sinu kood: „kas midagi uut on?“ Webhooki puhul teeb päringu teine pool. Sinu süsteem peab olema valmis vastu võtma, mitte küsima.

Kuidas webhook päriselt töötab

1. Sa paned paika aadressi

   See on sinu serveri URL, tavaliselt üks kindel tee nagu /webhooks/makse. Aadress peab olema avalikult kättesaadav ja HTTPS-i taga.

2. Sündmus toimub

   Klient tasub, arve kinnitatakse, dokument allkirjastatakse. Teenusepakkuja teeb sündmusest kirje ja saadab selle kohe sinu aadressile.

3. Sinu server vastab kiiresti

   Vastuseks piisab lühikesest kinnitusest. Kogu töö tehakse pärast seda taustal, sest aeglane vastus loetakse ebaõnnestunuks ja teade saadetakse uuesti.

4. Kordused ja kordussaatmised

   Sama sündmus võib tulla mitu korda. Sinu kood peab kontrollima sündmuse identifikaatorit ja jätma teise korra vahele.

Näide: makse laekumine

E-pood saadab kliendi pangalingi lehele. Kui makse õnnestub, saab pood webhooki kaudu teate ja märgib tellimuse makstuks. Ilma webhookita peaks pood iga paari minuti tagant küsima pangalt „kas see makse on nüüd tehtud“, mis tähendab palju tühje päringuid ja olukorda, kus klient näeb tellimust „ootel“ ka siis, kui raha on juba laekunud.

Sama muster töötab arvetega, dokumentide allkirjastamisega ja logistikaga. Kõikjal on küsimus üks: kas sündmuse toimumisest peab teine süsteem teada saama sekunditega. Kui vastus on jah, on webhook õige vahend, ja selle ehitamise maht sõltub sellest, kui palju sündmusi ja erandeid tuleb käsitleda. Sama teemat laiendab artikkel API integratsioonid.

Webhook või küsitlemine

Neli tüüpviga

• Allkirja ei kontrollita. Siis saab aadressi teadja saata võltsitud sündmuse. Allkirja saladus on võti, aadressi teadmine ei ole.
• Töö tehakse päringu sees. Kui vastus võtab kaua aega, loeb saatja selle ebaõnnestunuks ja saadab uuesti, mistõttu sama töö jookseb mitu korda.
• Idempotentsust ei ole. Sama teate teine tulek loob teise arve või teise kirje. Iga sündmuse id tuleb salvestada.
• Logi puudub. Kui teade jääb tulemata, ei ole kuskilt näha, mida saadi ja mida mitte. Sissetulevad teated tuleb logida koos oleku ja veaga.

Töö ja kulu

Ühe lihtsa webhooki vastuvõtja on hinnanguliselt päevatöö, kui sündmusi on üks ja erandeid vähe. Töö kasvab kordussaatmiste käsitlemise, logide ja käsitsi uuesti saatmise vajadusega, sest just need osad otsustavad, kas integratsioon peab vastu ka siis, kui midagi läheb valesti. Reeglina ei ole küsimus keerulises koodis, vaid selles, kas keegi on läbi mõelnud, mis saab siis, kui sama teade tuleb kaks korda või ei tule üldse.

Enne ehitust tasub vaadata, mida vastaspool päriselt pakub: korduskatseid, sündmuste logi, allkirja algoritmi ja testkeskkonda. Need neli asja määravad töö mahu rohkem kui sinu enda kood. Liidestamise üldpildi kohta vaata tarkvaraarenduse lehte.