Kaip nustatyti webhook adresą?

Webhook adresas – jūsų sistemos adresas, kuriuo INVOX praneša apie dokumentus. Adresai tvarkomi kortelėje Webhook’ai, tame pačiame skirtuke API kaip ir API raktai. Adresas pradeda veikti tik po sėkmingos bandomosios siuntos.

Prieš pradedant

• Adresus tvarko tik įmonės administratorius. Nariui skirtukas API nerodomas – žr. Kuo skiriasi administratorius ir narys?.
• Nustatymus atversite šoninės juostos nuoroda Bendrieji nustatymai. Atsidarys skirtukas Profilis.
• Reikia veikiančios priimančiosios sistemos. Adresą, kuris priima POST užklausą, paruošia jūsų programinės įrangos tiekėjas arba IT darbuotojas. 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ų viršuje spauskite skirtuką API.

   Po kortele API raktai bus kortelė 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 beveik dvi paras. Kol adresų nėra, rodoma Webhook adresų dar nėra.

   

2. Kortelėje Webhook’ai spauskite Pridėti adresą.

   Atsidarys langas Pridėti webhook adresą. Jo pradžioje rašoma Adresas lieka nepatvirtintas, kol nepavyksta viena bandomoji siunta — tikri įvykiai siunčiami tik po to.

   

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, mygtukas Pridėti adresą lieka neaktyvus.

   

   Šalis šiuose aprašuose – tai jūsų klientas. Jei dokumente abi pusės yra jūsų klientai, gausite po atskirą pranešimą kiekvienam.

   upload.rejected siunčiamas, kai INVOX nepriima failo, kad ir kokiu keliu jis atkeliavo. Jei failą atmeta pati API užklausa, šis įvykis nesiunčiamas – atsakymas jau gautas.

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.

   

   Pasirodys pranešimas Bandomoji siunta įtraukta į eilę — rezultatas pasirodys žemiau po akimirkos. Tai dar ne rezultatas. Po adreso eilute išsiskleis siuntų sąrašas: kai jūsų sistema atsako 2xx kodu, siunta tampa Pristatyta, o adresas – Aktyvus. Jei būsena nepasikeitė, po kelių sekundžių atnaujinkite puslapį.

   Bandomoji siunta yra tikra: ji pasirašoma 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.

Turinyje siunčiami tik identifikatoriai, o ne sąskaitos faktūros duomenys. Laukas related_object.url nurodo, kur dokumentą atsiimti per API – žr. Kas yra INVOX API?. Gavus invoice.approved, atsiimtoje sąskaitoje faktūroje jau yra automatiškai parinkti eilučių kodai ir laukai, kuriuos užpildė kliento taisyklės. Žr. Kaip veikia taisyklės, kurios užpildo laukus?.

Jūsų sistema turi atsakyti 2xx kodu per 12 sekundžių. Ilgesnius darbus atlikite jau atsakę, kitaip siunta laikoma nepavykusia.

Ta pati siunta gali ateiti ne kartą. Siuntos identifikatorius per visus bandymus nesikeičia, todėl pagal jį atmeskite pasikartojimus. Jei tą patį įvykį pažymėjote keliems adresams, kiekvienas gauna atskirą siuntą su savo identifikatoriumi.

Kartais ta pati sąskaita faktūra iš kliento sąrašo Sąskaitos trumpam dingsta ir vėl sugrįžta. Tada invoice.approved siunčiamas dar kartą, su nauju identifikatoriumi. Tokį pranešimą vertinkite kaip ženklą iš naujo atsiimti sąskaitos faktūros duomenis.

Kaip patikrinti parašą

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. Antraštėje kiekvienas parašas rašomas po žymos v1,.

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

Atmeskite siuntas, kurių laiko žyma nuo jūsų laikrodžio skiriasi daugiau nei 5 minutėmis. Taip pakartotinai atsiųsta sena siunta nebus priimta.

Kaip kartojamos nepavykusios siuntos

Nepavykusi siunta kartojama automatiškai, vis ilgesnėmis pertraukomis. Paskutinis bandymas įvyksta maždaug po dviejų parų. Kada bus kitas bandymas, rodo siuntų sąrašo stulpelis Kitas bandymas.

Išnaudojus visus bandymus, siunta tampa Atsisakyta ir nebekartojama. Pakartoti jos INVOX nustatymuose negalima. 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 sėkmingų siuntų nebuvo, stulpelyje Paskutinė siunta 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 išsiuntimo.
• 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 arba pristabdytas.

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 INVOX nebus. Vienintelė vieta, kurioje tai matyti, yra šis skirtukas. Todėl reguliariai žiūrėkite stulpelį Klaidos ir aiškinkitės kiekvieną nenulinę reikšmę. Užvedę pelę ant skaičiaus, pamatysite, ką atsakė jūsų sistema.

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 langą Redaguoti webhook adresą 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. Jau suplanuotos 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 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?

• Rodoma Įveskite visą adresą, prasidedantį https://. Įrašykite visą adresą su https:// pradžioje.
• Rodoma Šiuo adresu webhook’ų siųsti negalima. Jis turi būti viešas HTTPS adresas. Dažniausia priežastis – adresas prasideda http, o leidžiamas tik https. Jei adresas prasideda https, patikrinkite toliau aprašytas sąlygas.
• Adresas atmetamas, nors prasideda https. Adrese negali būti prisijungimo vardo ir slaptažodžio. 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.
• Adresas Išjungtas, o bandomosios siuntos išsiųsti nepavyksta. Meniu spauskite Įjungti. Jei rodoma Įjungti (pirma išsiųskite bandymą), adresas dar nė karto neveikė – ištrinkite jį ir pridėkite iš naujo.
• Bandomoji siunta pavyko, bet įvykių negaunate. Patikrinkite, ar pažymėti reikiami įvykiai ir ar būsena yra Aktyvus.
• Siunta rodoma Atsisakyta. Pakartoti jos INVOX nustatymuose 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 panaikinti API raktą?
• Kas vyksta su įkeltu dokumentu: būsenos
• Kodėl dokumentas atmestas?