Kaip nustatyti webhook adresą?

Webhook adresas – jūsų sistemos adresas, kuriuo INVOX praneša apie kiekvieną užbaigtą dokumentą. Adresai tvarkomi dalyje Webhook’ai, tame pačiame nustatymų puslapyje kaip ir API raktai. Adresas pradeda veikti tik po sėkmingos bandomosios siuntos.

Prieš pradedant

• Šią skiltį mato tik įmonės administratorius – žr. Kuo skiriasi administratorius ir narys?. Kaip ją atverti, aprašyta straipsnyje Kaip sukurti ir atšaukti API raktą?.
• Reikia veikiančios priimančiosios sistemos. Adresą, kuris priima POST užklausą, paruošia jūsų sistemą prižiūrintis specialistas. INVOX tik siunčia.
• Adresas turi būti viešas ir naudoti HTTPS.
• Pasiruoškite, kur įrašysite pasirašymo raktą. Jis parodomas vieną kartą.
• Vienai įmonei leidžiama iki 10 adresų.

Žingsniai

1. Nustatymų sąraše spauskite API.

   

   Puslapio apačioje bus dalis Webhook’ai. Jos apraše rašoma Dokumentui pasiekus galutinę būseną, INVOX iškart siunčia pasirašytą HTTPS užklausą į jūsų sistemas — jungčiai nebereikia periodiškai klausinėti. Nepavykusios siuntos kartojamos iki 48 valandų. Kol adresų nėra, rodoma Webhook adresų dar nėra.

2. Dalyje Webhook’ai spauskite Pridėti adresą.

   

   Atsidarys langas Pridėti webhook adresą su adreso lauku ir įvykių sąrašu.

3. Lauke Adreso URL įrašykite savo sistemos adresą.

   

   Lauke rodomas pavyzdys https://erp.example.com/hooks/invox, o po juo – Turi būti viešas HTTPS adresas. Vidiniai, loopback ir debesijos metaduomenų adresai atmetami.

4. Dalyje Įvykiai pažymėkite, apie ką norite gauti pranešimus.

   
   • invoice.approved — patikrinta sąskaita paruošta apskaitai (po vieną kiekvienai šalies kopijai)
   • invoice.rejected — dokumentas atmestas jau po to, kai buvo sukurtas sąskaitos įrašas
   • upload.rejected — įkeltas failas netapo sąskaita

   Iš pradžių pažymėtas invoice.approved. Nepažymėjus nė vieno įvykio, adreso išsaugoti nepavyks.

   Šalis šiuose aprašuose ir yra įmonė: jei apskaitote abi to paties dokumento puses, gausite po atskirą pranešimą kiekvienai.

5. Lango apačioje spauskite Pridėti adresą.

   Atsidarys langas Pasirašymo raktas. Jame rodoma Nukopijuokite raktą dabar — jis saugomas užšifruotas ir daugiau nebus parodytas. Naudokite jį kiekvienos gautos užklausos webhook-signature antraštei patikrinti.

6. Spauskite Kopijuoti.

   Trumpam pasirodys Nukopijuota. Prieš uždarydami langą, įrašykite raktą į priimančiąją sistemą. Tik tada spauskite Baigta. Rakto atkurti nebus galima, bet jį galima pakeisti nauju: Praradote? Pakeiskite raktą ir gausite naują.

7. Adreso eilutėje spauskite Siųsti bandomąją.

   Naujas adresas iš pradžių yra Nepatvirtintas ir negauna nieko. Adresą įjungia būtent sėkminga bandomoji siunta.

   Žalias pranešimas reiškia tik tai, kad siunta įtraukta į eilę. Tikrąjį rezultatą pamatysite išskleidę siuntų sąrašą po adreso eilute. Kai jūsų sistema atsako 2xx kodu, būsena tampa Aktyvus.

   Bandomoji siunta yra tikra: ji pasirašoma, siunčiama ir kartojama taip pat, kaip įprastas įvykis.

Ką gauna jūsų sistema

Kiekviena siunta – POST užklausa su JSON turiniu. Kartu siunčiamos antraštės webhook-id, webhook-timestamp ir webhook-signature. Antraštės user-agent reikšmė – INVOX-Webhooks/1.

Parašas skaičiuojamas HMAC-SHA256 algoritmu ir užkoduojamas base64. Pasirašomas tekstas sudaromas iš siuntos identifikatoriaus, laiko žymos ir tikslaus užklausos turinio, sujungtų taškais. Naudojama Standard Webhooks v1 schema, todėl tinka ir paruoštos tikrinimo bibliotekos.

Pasirašymo raktas prasideda whsec_. Skaičiuojant HMAC naudojama ne visa eilutė, o po šios pradžios einanti dalis, iškoduota iš base64.

Vienam bandymui skiriama 12 sekundžių. Per tą laiką jūsų sistema turi atsakyti 2xx kodu, o ilgesnius darbus atlikti jau atsakius.

Turinyje siunčiami tik identifikatoriai, o ne sąskaitos faktūros duomenys. Patį dokumentą atsiimkite per API – žr. Kas yra INVOX API?.

Ta pati siunta gali ateiti ne kartą. Siuntos identifikatorius per visus bandymus nesikeičia, todėl pagal jį atmeskite pasikartojimus. Jei tas pats įvykis įrašytas keliems adresams, kiekvienas gauna atskirą siuntą su savo identifikatoriumi.

Kaip kartojamos nepavykusios siuntos

Nepavykusi siunta kartojama automatiškai. Iš viso atliekami devyni bandymai.

Pertraukos tarp jų ilgėja: 30 sek., 2 min., 10 min., 30 min., 2 val., 6 val., 12 val. ir 24 val. Kiekviena pertrauka dar šiek tiek pakoreguojama, kad siuntos nesugultų vienu metu.

Skilties apraše nurodyta, kad siuntos kartojamos iki 48 valandų. Tai viršutinė riba, kurios grafikas nepasiekia. Paskutinis bandymas įvyksta anksčiau, nei praeina dvi paros.

Todėl dvi paras neveikusi sistema pavėluotos siuntos nebegaus. Atstatę priimančiąją sistemą, praleistus dokumentus atsiimkite per API.

Ką reiškia adreso būsena

Sąraše prie kiekvieno adreso rodoma Adresas, Įvykiai, Būsena, Paskutinė siunta ir Klaidos. Kol siuntų nebuvo, rodoma Niekada.

• Aktyvus – adresas veikia.
• Nepatvirtintas – bandomoji siunta dar nepavyko, todėl adresas nieko negauna.
• Pristabdytas – adresas anksčiau veikė, bet buvo sąmoningai sustabdytas.
• Išjungtas – adresą išjungė INVOX. Šalia rodoma priežastis.

Stulpelyje Įvykiai matomi neišversti įvykių pavadinimai – tokie patys kaip pažymėjimo langeliuose.

Siuntų sąrašas

Po kiekvieno adreso eilute išskleidžiamas paskutinių siuntų sąrašas. Jį atversite rodyklės mygtuku eilutės kairėje. Jo stulpeliai: Įvykis, Būsena, Bandymai, Atsakas, Įvyko ir Kitas bandymas. Kol siuntų nėra, rodoma Siuntų dar nėra.

• Eilėje – siunta laukia savo eilės.
• Siunčiama – siunčiama dabar.
• Pristatyta – jūsų sistema atsakė sėkmingai.
• Nepavyko — bus kartojama – bandymas nepavyko, bet bus kartojamas.
• Atsisakyta – visi bandymai išnaudoti, daugiau nebekartojama.
• Neišsiųsta — adresas išjungtas – siunta nesiųsta, nes adresas tuo metu buvo išjungtas.

Rodoma 50 naujausių vieno adreso siuntų, o įrašai saugomi 30 dienų. Ištrynus adresą, kartu dingsta ir visa jo siuntų istorija.

Stulpelyje Įvykis bandomoji siunta žymima žodžiu ping.

Kai INVOX išjungia adresą

Po 20 nesėkmingų bandymų iš eilės adresas išjungiamas. Būsena tampa Išjungtas, o šalia rodoma per daug klaidų iš eilės. Vienas sėkmingas atsakas skaitiklį atstato į nulį.

Jei jūsų sistema atsako 410, adresas išjungiamas iškart. Tada rodoma priežastis adresas atsakė 410 Gone.

Apie išjungimą niekas nepranešama. Nei laiško, nei pranešimo portale nebus. Vienintelė vieta, kurioje tai matyti, yra šis puslapis. Todėl reguliariai peržiūrėkite stulpelį Klaidos ir aiškinkitės kiekvieną nenulinę reikšmę. Užvedę pelę ant skaičiaus, pamatysite, ką atsakė jūsų serveris.

Adresą galima įjungti iš naujo. Tada išvaloma išjungimo priežastis ir klaidų skaitiklis. Bet praleistos siuntos nepakartojamos: dokumentus, apdorotus adreso išjungimo metu, atsiimkite per API.

Jei adresas dar nė karto neveikė sėkmingai, įjungti nepavyks. Meniu punktas tada rodomas kaip Įjungti (pirma išsiųskite bandymą).

Kaip pakeisti, pristabdyti arba ištrinti adresą

Veiksmų meniu atversite mygtuku su trimis taškais adreso eilutės gale, šalia mygtuko Siųsti bandomąją. Jame yra Redaguoti, Pristabdyti arba Įjungti, Pakeisti pasirašymo raktą ir Ištrinti.

Redaguoti atveria tą patį langą su adresu ir įvykiais; pakeitimą įrašysite mygtuku Išsaugoti. Pakeitus adresą, jis vėl tampa Nepatvirtintas ir nustoja gauti siuntas, kol nepavyks nauja bandomoji siunta. Apie tai įspėjama dar prieš išsaugant.

Pristabdyti sustabdo veikiantį adresą: būsena tampa Pristabdytas, o siuntos nebesiunčiamos. Kol adresas pristabdytas, pranešimai jam nekaupiami, o eilėje jau buvusios siuntos baigiasi būsena Neišsiųsta — adresas išjungtas. Grąžinsite adresą veiksmu Įjungti, o per pristabdymą praleistus dokumentus atsiimkite per API.

Ištrinti pašalina adresą negrįžtamai; veiksmą patvirtinsite lange Ištrinti šį adresą?.

Kaip pakeisti pasirašymo raktą

Raktą galima pakeisti bet kada, pavyzdžiui, jei jis galėjo nutekėti. Adreso meniu spauskite Pakeisti pasirašymo raktą.

Atsidarys langas Pakeisti pasirašymo raktą?. Jame nurodomas adresas ir paaiškinama, kad naujas raktas bus parodytas vieną kartą, o dabartinis dar veiks 24 valandas. Spauskite Pakeisti raktą.

Per tas 24 valandas siuntos pasirašomos abiem raktais. Antraštėje webhook-signature siunčiami abu parašai, atskirti tarpu. Priimančiajai pusei pakanka, kad sutaptų bent vienas. Todėl spėję įdiegti naują raktą, neprarasite nė vienos siuntos.

Pasibaigus 24 valandoms, senasis raktas nustoja galioti.

Ką daryti, jei nepavyko?

• Klaidų pranešimai rodomi angliškai. Šios dalies klaidas grąžina serveris, o portalas parodo jas originalo kalba. Dažniausia priežastis – adresas įrašytas su http. Leidžiamas tik https.
• Adresas atmetamas, nors prasideda https. Adrese negali būti prisijungimo vardo ir slaptažodžio. Adreso domenas turi būti pasiekiamas iš viešo interneto, o vieši turi būti visi IP adresai, kuriuos jam priskiria DNS. Užtenka vieno vidinio IP adreso, kad adresas būtų atmestas.
• Rodoma, kad pasiektas didžiausias adresų skaičius. Vienai įmonei leidžiama iki 10 adresų. Ištrinkite nebenaudojamą.
• Bandomosios siuntos išsiųsti nepavyksta. Tarp dviejų bandomųjų siuntų būtina 30 sekundžių pertrauka.
• Bandomoji siunta pavyko, bet įvykių negaunate. Patikrinkite, ar pažymėti reikiami įvykiai ir ar būsena yra Aktyvus.
• Siunta rodoma Atsisakyta. Pakartoti jos portale negalima. Praleistus duomenis atsiimkite per API arba rašykite support@invox.lt.
• Parašas nesutampa. Tikrinkite tikslų gautą turinį, o ne iš naujo suformuotą JSON. Patikrinkite ir tai, ar HMAC skaičiuojamas iš iškoduotos rakto dalies.

Susiję straipsniai

• Kas yra INVOX API?
• Kaip sukurti ir atšaukti API raktą?
• Kas vyksta su įkeltu dokumentu: būsenos
• Kodėl dokumentas atmestas?