Webhookit

Webhookien käyttö Manu Online-ohjelmassa

Webhookit ovat automatisoituja viestejä, joita lähetetään, kun käyttäjä tekee jonkin toimen Manu Onlinessa. Tietoja lähetetään määritettyyn osoitteeseen. Vastaanottavan palvelimen pitää ”kuunnella” onko viestejä tulossa eli sitä kutsutaan nimellä ”listener”. Tietoja voi Manu Onlinesta hakea myös API:n kautta, mutta webhookin käytössä on se huomattava etu, että virhetilanteista tulee käyttäjälle välitön palaute ja siirtoa voi kokeilla uudeelleen.

 

Webhookit ovat käytössä omissa sovelluksissa eli ns. private app järjestelmissä. Näin "listener" voi varmistaa, että tiedot vastaanotetaan oikeasta lähteestä eli Manu Online -tililtä.

 

Webhook listener pitää toteuttaa omaan sovellukseesi, jotta prosessi saadaan toimimaan. Suositellaan vahvasti käyttämään kryptattua yhteyttä eli https:// endpointtia.Siirrettävässä tiedossa on allekirjoitus vastannottavaa ’listener’ toimintoa varten, jolla varmistetaan, että tieto tulee nimenomaan omasta Manu Online -järjestelmästäsi. Allekirjoituksessa on liitettävän sovelluksen asiakassalaisuus. Allekirjoitus on md5 kryptattua dataa, jota kutsutaan ”Manu-MD5-VerifyCode”. Vastaanottavan puolen on varmistettava allekirjoituksen oikeellisuus ennenkuin saapuva tieto hyväksytään. Tämän artikkelin lopussa on esimerkkikoodi, miten allekirjoitus varmistetaan.Lähetettävä datapaketti on sama json data, minkä api -kutsu palauttaa.Webhook testataan kerran. Käyttäjä saa virheilmoituksen, jos testi epäonnistuu. Käyttäjä voi yrittää toimintoa uudelleen, tai sovellus voidaan ohjelmoida hakemaan tietoja API:sta säännöllisesti tarkistaakseen, että kaikki on vastaanotettu, esim. yöllinen kutsu luetteloon myyntitilauksista, jotka on luotu kyseisenä päivänä.

Huomaa, jos käytät Zapieria siinä integraatiomme hyödyntää webhookkia myös. Niitä ei ole näkyvissä, mutta käyttäjä saattaa saada webhook virheitä, jos vaikka Zapier- tilisi ei ole enää voimassa.

 

Webhookien luonti

Webhookin luonti edellyttää, että ensin on luotu oma sovellus, Private application. Mene sitten Hallinto – Integraatiot – Webhookit. Nimeä se ja valitse sovellustunnus. Voit laittaa jonkin kuvaavan kommentin.

 

 

Seuraavat Manu Onlinessa tehtävät toimet voidaan valita käynnistämään webhookin:

Webhookin tyyppi	Käynnistävä toimi
Sopimus/Aktivointi	Sopimuksen aktivointi
Nimike/Tallenna	Nimikkeen tallennus
Kumppani/Tallenna	Kumppanin tallennus
Keruulista/Luonti	Työerän keruulistan luonti
Ostotilaus/Aktivointi	Ostotilauksen aktivointi
Myyntitilaus/Aktivointi	Myyntitilauksen aktivointi
Sarjanumero/Tallenna	Sarjanumeron luonti työerässä, sarjanumerotiedon tallennus, sarjanumeroidun nimikkeen toimitus.
Myyntilasku	Myyntilaskun aktivointi
Ostolasku	Ostolaskun aktivointi
Myynnin toimitus/Aktivointi	Myyntitilauksen toimituksen aktivointi
Myynnin toimitus/Lähetä	Lisää painikkeen, jolla lähetetään viesti rakenteilla olevasta lähetyksestä, kun tämä webhookin luodaan.
Kumppani API/Post	Luodaan uusi kumppani APIa käyttäen
Vastaanotto/Lähetä	Lisää painikkeen, jolla lähetetään viesti rakenteilla olevasta vastaanottoviestistä, kun tämä webhookin luodaan.

 

Webhook loki

Kaikista webhookeista talletetaan lokitietoa Jos webhookin vastaanottava puoli palauttaa muun html -koodin kuin 200, se kirjataan lokiin virheeksi. Jos webhook-lisener palauttaa jonkin muun html-koodin kuin 200, se kirjataan virheeksi.

 

Webhookien loki -välilehdeltä näet lokitiedot. Oletuksena on, että vain virheilmoitukset näytetään. Valintaruudun merkitsemällä saa esiin myös onnistuneet tapahtumat.

 

Esimerkkikoodi, miten allekirjoitus varmistetaan

class Program { static void Main(string[] args) { var secret = ""; //the value should be your ClientSecret1 var md5 = ""; var payload = ""; //replace it with the body of webhook request if (md5 == GenerateVerifyCodeWithPayload(secret, payload)) Console.WriteLine("Signature is correct"); else Console.WriteLine("Invalid Signature"); Console.ReadKey(); } private static string GenerateVerifyCodeWithPayload(string accountKey, string payload) { string source = payload + accountKey; return new MD5Encryptor().MD5(source, MD5Encryptor.MD5Type.bytes32); } } public class MD5Encryptor { public enum MD5Type{ bytes16 = 0, bytes32 = 1 } public string MD5(string strSource, MD5Type type) { byte[] dataToHash = (new ASCIIEncoding()).GetBytes(strSource); HashAlgorithm algorithm = (HashAlgorithm)CryptoConfig.CreateFromName("MD5"); byte[] hashvalue = algorithm.ComputeHash(dataToHash); var i = 0; string rs = ""; switch (type) { case MD5Type.bytes16: for (i = 4; i <= 11; i++){ rs += String.Format("{0:X}", hashvalue[i]).PadLeft(2, '0').ToLower(); } break; default: for (i = 0; i <= 15; i++){ rs += String.Format("{0:X}", hashvalue[i]).PadLeft(2, '0').ToLower(); } break; } return rs; } }