Webhook on tiedonvälitysmenetelmä, jonka avulla verkkokehittäjät voivat luoda omia HTTP-kutsujaan, jotka suoritetaan jonkin määrätyn tapahtuman yhteydessä.

Webhooks-laajennus poistuu käytöstä lokakuussa 2022

Olemassaolevat Webhooksilla toteutetut sovellukset toimivat edelleen, mutta uusien luomista ei suositella.

Laajennuksen korvaajaksi on saatavilla uusi Webhooks API, joka kuuluu MyCashflow API:in.

Katso lisätietoja siirtymisestä uuteen Webhooksiin.

Seuraavat toiminnot ovat tällä hetkellä mahdollisia MyCashflow'n Webhooks-laajennuksen avulla:

  • Tilaustietojen hakeminen
  • Tilausten käsitteleminen
  • Tilauskommenttien lisääminen

Voit käyttää laajennusta integroidaksesi verkkokauppasi tilausten osalta johonkin ulkopuoliseen ohjelmaan. Integrointeja voit toteuttaa myös MyCashflow'n REST API:n avulla.

Laajennukset eivät ole käytettävissä MyCashflow Free -palvelupaketissa.

Hinnoittelu

Laajennuksen käyttö on maksutonta.

Toimintaperiaatteet

Webhooksia käytetään lähettämällä jollain ohjelmointikielellä (usein cURL-ohjelman avulla) HTTP-pyyntö verkkokaupan Webhooks-osoitteeseen. MyCashflow'n Webhooks-laajennus palauttaa tuosta osoitteesta XML-muotoisen vastauksen pyyntöön.

GET-tyyppisiä Webhooks-komentoja on mahdollista käyttää myös syöttämällä haluttu Webhooks-osoite selaimen osoiteriville. Näin voit helposti testata Webhooks-pyyntöjä verkkokaupassasi.

Verkkokauppaan tulevista tilauksista lähetetään aina automaattinen POST-pyyntö laajennuksen asetuksissa määriteltyyn osoitteeseen (paitsi MyCashflow API:n kautta luotujen tilausten kohdalla).

Alla on esitelty Webhooks-pyynnön kaikki osat:

  1. Kaikkien Webhooks-pyyntöjen yhteyspiste on https://KAUPANOSOITE.mycashflow.fi/webhooks/
  2. Yhteyspisteen perään lisätään haluttu toiminto (katso lista sallituista toiminnoista): https://KAUPANOSOITE.mycashflow.fi/webhooks/get
  3. Seuraavaksi pyyntöön lisätään toimintoon liittyvät GET- tai POST-parametrit: https://KAUPANOSOITE.mycashflow.fi/webhooks/get?order=n
  4. Viimeiseksi pyyntöön lisätään verkkokaupan yksilöllinen API-avain: https://KAUPANOSOITE.mycashflow.fi/webhooks/get?order=n&key=jyghji765rfghji
    • Kun suoritat Webhooks-pyynnön selaimen osoiterivillä, API-avainta ei tarvitse lisätä osoitteeseen, kunhan olet kirjautunut verkkokaupan hallintatyökaluun.

Alla on esimerkki Webhooks-pyynnöstä, jossa lähetetään asiakkaalle julkinen tilauskommentti:

https://KAUPANOSOITE.mycashflow.fi/webhooks/process
    action=add_comment
    order=23
    message="Kommenttia pukkaa"
    public_message=1
    key=kjhbnko987654e

Asennus ja käyttöönotto

Lue myös laajennuksien yleiset asennus- ja käyttöönotto-ohjeet.

Laajennukset eivät ole käytettävissä MyCashflow Free -palvelupaketissa.

Määritä laajennuksen asetuksissa osoite, johon verkkokaupasta lähetetään Webhook-kutsuja, sekä tunnistautumiseen käytettävä API key.

Webhooks-osoitteeseen lähetetään verkkokauppaan tehdyistä tilauksista automaattinen POST-pyyntö, joka sisältää tilauksen tiedot.

Kun olet määrittänyt Webhooksin asetukset, testaa laajennuksen toimivuutta lähettämällä jokin pyyntö syöttämääsi osoitteeseen (saatavilla olevat toiminnot esitelty alla). Voit esimerkiksi tehdä testitilauksen, josta lähetetään automaattinen ilmoitus

Webhooks-toiminnot

Alla on listattu kaikki MyCashflow'n Webhooks-laajennuksen toiminnot ja niiden parametrit.

Katso myös esimerkkejä toimintojen soveltamisesta käytännössä.

Lisätietoa Webhooksin XML-tietorakenteesta löydät #concept_eyp_zpg_4db-kappaleesta.

POST /webhooks/processaction=deliver
Merkitsee tilauksen toimitetuksi.
orderKokonaislukuKäsiteltävän tilauksen ID-numero
send_email0 / 1

Arvolla 1 lähetetään toimitusvahvistus, josta lähtee myös sähköposti asiakastietojen ja toimitusosoitteen sähköpostiin. Oletuksena viestiä ei lähetetä (arvo 0).

POST /webhooks/processaction=add_comment
Lisää tilaukselle kommentin.
orderKokonaislukuKäsiteltävän tilauksen ID-numero
public_message0 / 1Määrittää onko kommentti julkinen viesti (arvolla 1), josta lähtee myös sähköposti asiakastietojen ja toimitusosoitteen sähköpostiiin. Oletuksena kommentti ei ole julkinen (arvo 0).
messageTekstiTilauskommentin sisältö tekstimuodossa
GET /webhooks/get
Käytetään yhden tai usean tilauksen hakemiseen ID-numeroiden perusteella.
orderKokonaislukuHaettavan tilauksen ID-numero
order_idsKokonaislukutaulukko

Käytetään useiden tilauksien hakemiseen ID-numerojen perusteella.

Esim. order_ids[]=1&order_ids[]=4&order_ids[]=56

GET /webhooks/changes

Käytetään tilausten hakemiseen niiden luontiajankohdan ja muutosten perusteella.

Palauttaa aina vain 100 tilausta kerrallaan halutusta ajankohdasta alkaen.

created_after_tsMerkkijono

Unix timestamp -muotoinen aikamääre, jonka jälkeen luodut tilaukset halutaan hakea.

Esim. created_after_ts=1483185600

updated_after_tsMerkkijonoUnix timestamp -muotoinen aikamääre, jonka jälkeen päivittyneet tilaukset halutaan hakea.
GET /webhooks/send
Käytetään epäonnistuneen Webhooks-sanoman lähettämiseen uudestaan.
orderKokonaislukuTilauksen ID-numero

Paluuarvot

Kaikki Webhooksin palauttama tieto on XML-muodossa. Alla näet esimerkin Webhooksin palauttamasta XML-sanomasta.

Näytä esimerkkitiedosto

Oheinen esimerkki on vastaus GET /webhooks/changes-pyyntöön, jolla haetaan tilauksia verkkokaupasta.

Paluusanomaan kuuluvat tilauksen, tilaajan ja tilattujen tuotteiden tiedot.

<Orders>
  <Order id="58">
    <OrderNumber>58</OrderNumber>
    <OrderedAt timestamp="1345401893">2012-08-19 21:44:53</OrderedAt>
    <OrderStatus>Open</OrderStatus>
    <OrderLanguage>fi</OrderLanguage>
    <Comments>K&amp;auml;sitteletteh&amp;auml;n pikaisesti, koska t&amp;auml;m&amp;auml; on kiireisempi kuin muut tilaukset.</Comments>
    <PaymentMethod PaymentID="7">Checkout</PaymentMethod>
    <PaymentReference>20120819001532</PaymentReference>
    <PaymentStatus>Paid</PaymentStatus>
    <ShippingMethod ShippingID="6">SmartPOST</ShippingMethod>
    <ShippingWeight>0.5</ShippingWeight>
    <ShippingPackages>1</ShippingPackages>
    <Documents>
      <Receipt>http://smo43.mycashflow.fi/orderstatus/58/receipt/52d07914f6bcdf448084320f3de6a816</Receipt>
      <DispatchNote>http://smo43.mycashflow.fi/orderstatus/58/dispatchnote/ba4be2b2ed682be3c646be5ef7f3a77d</DispatchNote>
      <Invoice>http://smo43.mycashflow.fi/orderstatus/58/invoice/f358b6fe49b80c91425137059e0cb49b</Invoice>
    </Documents>

    <CustomerInformation>
      <FirstName>Ismo</FirstName>
      <LastName>Ruotsalainen</LastName>
      <Company>Pulse247 Oy</Company>
      <BusinessID>FI21315706</BusinessID>
      <StreetAddress>Syväojankatu 3A</StreetAddress>
      <Zipcodeph>87100</Zipcodeph>
      <City>Kajaani</City>
      <Country>fi</Country>
      <Email allowMarketing="false">ismo@pulse247.info</Email>
      <Phone allowMarketing="false">020 741 9172</Phone>
      <IPAddress>85.29.85.227</IPAddress>
    </CustomerInformation>

    <ShippingAddress>
      <FirstName>Ismo</FirstName>
      <LastName>Ruotsalainen</LastName>
      <Company>Pulse247 Oy</Company>
      <StreetAddress>Syväojankatu 3A</StreetAddress>
      <Zipcodeph>87100</Zipcodeph>
      <City>Kajaani</City>
      <Country>fi</Country>
      <Phone>020 741 9172</Phone>
    </ShippingAddress>

    <Products>
      <Product>
        <ProductID>3</ProductID>
        <ProductName>Lacoste kävelykengät</ProductName>
        <Variation id="3">Valkoinen/42</Variation>
        <codeph>123123</codeph>
        <UnitPrice vat="0">41.28</UnitPrice>
        <Quantity>1</Quantity>
        <Total>41.28</Total>
        <Shipped>false</Shipped>
      </Product>

      <Product>
        <ProductID>1199</ProductID>
        <ProductName>Lahjakortti 100€</ProductName>
        <UnitPrice vat="0">66.12</UnitPrice>
        <Quantity>1</Quantity>
        <Total>66.12</Total>
        <Shipped>false</Shipped>

        <Campaign>
          <CampaignID>496</CampaignID>
          <NormalUnitPrice>82.6446</NormalUnitPrice>
        </Campaign>

      </Product>

      <Product>
        <ProductID PaymentID="7">PAYMENT</ProductID>
        <ProductName>Checkout</ProductName>
        <Quantity>1</Quantity>
      </Product>

      <Product>
        <ProductID ShippingID="6">SHIPPING</ProductID>
        <ProductName>SmartPOST</ProductName>
        <UnitPrice vat="0">5</UnitPrice>
        <Quantity>1</Quantity>
        <Total>5</Total>
      </Product>

    </Products>
  </Order>
</Orders>

Esimerkkejä

Alla on listattu esimerkkejä MyCashflow'n Webhooks-laajennuksella onnistuvista toiminnoista.

Katso myös kaikkien toimintojen tarkat kuvaukset ja käytettävissä olevat parametrit.

Yksittäisen tilauksen hakeminen

Voit hakea verkkokauppasi Webhooks-rajapinnan kautta yksittäisen tilauksen tiedot:

GET /webhooks/get?order=43&key=gvbnkiytfghu76tg

Kun haet yksittäisen tilauksen Webhooks-rajapinnasta, paluusanoman juurielementti on <Order>, joka sisältää tiedot tilauksesta, tilaajasta ja tuotteista.

Uusien tilausten hakeminen

Webhooks-laajennuksen avulla voit myös hakea verkkokauppaasi tulleita uusia tilauksia ulkoiseen järjestelmään.

GET /webhooks/changes?ts=n&key=jhbnji8765rfg

Normaali implementointi omaan sovellukseen menee niin, että sovellus kysyy rajapinnasta tapahtumia tietyn kellon ajan jälkeen ja käsittelee aineiston tilaukset. Lopuksi sovellus tallentaa viimeisimmän tilauksen timestamp-arvon talteen ja käyttää sitä seuraavassa kyselyssä.

Webhooksin palauttama tilauslista
<Orders time_from="1336738000" time_to="1345401893" orders="58">
	<Order id="1">
		<OrderNumber>1</OrderNumber>
		<OrderedAt timestamp="1336738023">2012-05-11 15:07:03</OrderedAt>
		...
	</Order>
	...
	<Order id="58">
		<OrderNumber>58</OrderNumber>
		<OrderedAt timestamp="1345401893">2012-08-19 21:44:53</OrderedAt>
		...
	</Order>
</Orders>

GET /webhooks/changes -pyynnön paluusanoma on muuten vastaava kuin yksittäistä tilausta kysyttäessä, paitsi koko XML-tiedoston juurielementti on <Orders>, jonka alla on jokaista palautunutta tilausta kohti oma <Order>-elementti.

<Orders>-elementin attribuuteissa on kerrottu miltä aikaväliltä tilauksia palautetaan ja kuinka monta tilausta aineistossa on kokonaisuutena. Myös yksittäisen tilauksen <OrderedAt>-elementille on lisätty attribuutti timestamp, joka kertoo suoraan tilauksen aikaleiman.

GET /webhooks/changes -rajapinnan tilaukset kannattaa käsitellä järjestyksessä ja tallentaa aina onnistuneen tilauksen jälkeen tilauksen oma timestamp-arvo talteen mieluummin kuin <Orders>-elementin time_to-arvo. Tällöin seuraava haku aloitetaan aina ensimmäisestä käsittelemättä jääneestä tilauksesta eikä välistä jää tilauksia noutamatta, jos käsittely on aiemmin epäonnistunut.

Valittujen tilauksien hakeminen

Voit hakea kerralla useita tilauksia käyttämällä seuraavaa Webhooks-pyyntöä:

GET /webhooks/get?order_ids[]=23&order_ids[]=43&order_ids[]=3&key=jhbnji8765rfg

Kun haet useita tilauksia, paluusanoman juurielementti on <Orders>, joka sisältää oman <Order>-elementin jokaiselle palautuneelle tilaukselle, samalla tavoin kuin GET /webhooks/changes -pyynnöllä.

Tilauksen ja sen kaikkien tuotteiden merkitseminen toimitetuksi

Voit merkitä Webhooks-pyynnöllä tilauksen toimitetuksi. Käytä tällöin seuraavia parametreja:

POST /webhooks/process
    action=deliver
    order=45
    send_email=1
    key=gvbnkiytfghu76tg

Esimerkissä lähetetään asiakkaalle toimitusvahvistus asettamalla parametri send_email=1.

Tilauskommentin lisääminen

Voit lisätä tilaukselle tilauskommentin, josta voit tarvittaessa lähettää asiakkaalle sähköposti-ilmoituksen. Käytä tällöin seuraavaa pyyntöä:

POST /webhooks/process
    action=add_comment
    message="Viestin sisältö"
    public_message=1
    key=jhbnji8765rfg

Esimerkissä asetettu kommentti lähetetään julkisesti asiakkaalle asettamalla attribuutti public_message=1.

Webhooks-sanoman lähettäminen uudelleen

GET /webhooks/send -pyynnöllä voit lähettää uudelleen epäonnistuneen sanoman. Toiminnolle annetaan order-parametrinä lähetettävän tilauksen tilausnumero.

GET /webhooks/send?order=34&key=jhbnji8765rfg