Webhookit
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. Voit lukea wikipediasta tarkemmin webhook -teknologiasta
Webhookit ovat käytössä omissa sovelluksissa eli ns. private app järjestelmissä. Luonti tapahtuu käyttäen meidän API työkaluja. Vastaanottava eli ’listener’ puoli pystyy varmistamaan, että tieto tulee oikeasta lähteestä eli esimerkiksi 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ää toimenpidettä uudestaan tai sovelluksesi voidaan ohjelmoida hakemaan säännöllisin välein tietoa API:sta ja tarkistamaan, että kaikki on vastaanotettu. Esimerkiksi öisin hakee listan myyntitilauksista, jotka päivän aikana on luotu.
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. Syötä oikea url -osoite ja valitse webhook – tyyppi. Lopuksi varmista, että valintaruutu Aktiivinen on merkitty.
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ä | Adds button for sending message of dispatch under construction when this webhook is created |
| Kumppani API/Post | Luodaan uusi kumppani APIa käyttäen |
| Vastaanotto/Lähetä | Adds button for sending message of receipt under construction when this webhook is created |
Webhook loki
Kaikista webhookeista talletetaan lokitietoa Jos webhookin vastaanottava puoli palauttaa muun html -koodin kuin 200, se kirjataan lokiin 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; } }