MyCashflow API:in on lisätty uusi Webhooks-toiminnallisuus, joka korvaa vanhan Webhooks-laajennuksen lokakuussa 2022. Lue tästä tiedotteesta lisää uuden ja vanhan Webhooks-toteutuksen eroista sekä uuden Webhooksin käyttöönotosta.

Uusi Webhooks API eroaa vanhasta toteutuksesta seuraavasti:

  • Ei graafista käyttöliittymää: Kaikki toiminnot on toteutettava integraatiosovelluksen koodissa.
  • Saatavilla alkaen Advanced-paketista: Webhooks API on osa MyCashflow API:a.
  • Datan muoto muuttuu: Uusi Webhooks API käyttää JSON-formaattia vanhan XML-muodon sijaan.

Tutustu myös seuraaviin materiaaleihin:

Uuden Webhooksin käyttöönotto

Uusi Webhooks otetaan käyttöön lähettämällä halutun verkkokaupan Webhooks-rajapintaan POST /api/v1/webhooks -pyyntö, jolla asetetaan Webhooks 1) seuraamaan määrättyä tapahtumaa (esim. tilausten saapuminen) ja 2) lähettämään siitä sanoma haluttuun URL-osoitteeseen.

Pyynnön lopputuloksena verkkokauppaan luodaan Webhooks-tilaus, jonka tiedot API palauttaa pyynnön paluusanomassa.

Alla olevassa esimerkissä asetetaan Webhooks seuraamaan verkkokaupan tilausten luomista:

POST /api/v1/webhooks
{
  "topic": "order.created",
  "expands": [
    "payments",
    "shipments"
  ],
  "url": "https://www.example.com"
}

Pyynnön onnistuessa API lähettää paluusanomana JSON-objektin, joka sisältää Webhooks-tilauksen yksilöllisen UUID-tunnisteen sekä muita tietoja tilauksesta.

Tallenna vastauksena saatu JSON-objekti esimerkiksi integraation sisältämään tiedostoon tai tietokantaan.

Paluusanoman sisältämää UUID-tunnistetta käytetään validoimaan rajapinnan lähettämiä Webhook-sanomia, mikä on tärkeä tietoturvatoimi.

Alla on esimerkki onnistuneen Webhook-tilauksen paluusanomasta:

{
    "data": {
        "uuid": "083c584d-ae65-11ec-aef4-0242ac130002",
        "user_id": 2,
        "topic": "order.created",
        "expands": [
            "payments",
            "shipments"
        ],
        "url": "https://www.example.com"
    }
}

Webhooks-toimintojen päivitys uuteen rajapintaan

Vanhan Webhooksin tilausten käsittelytoiminnot eivät ole käytettävissä uudessa rajapinnassa, joten niitä käyttävät integraatiot on päivitettävä käyttämään MyCashflow API:n vastaavia toimintoja, jotka käydään läpi alla.

  • POST /webhooks/process?action=deliver: Merkitsee tilauksen toimitetuksi.
    Korvaava toiminto:
  • POST /webhooks/process?action=add_comment: Lisää tilaukselle kommentin.

    Korvaava toiminto: Voit lisätä tilauksille tilauksille kommentteja kutsulla POST /api/v0/orders/{orderId}/comments.

  • GET /webhooks/get?order={orderId}: Hakee yksittäisen tilauksen.

    Korvaava toiminto: Voit hakea yksittäisen tilauksen kutsulla GET /api/v0/orders/{orderId}.

  • GET /webhooks/changes?created_after_ts/update_after_ts: Hakee tilaukset, jotka on luotu tai päivitetty määrätyn ajan jälkeen.
    Korvaava toiminto: Voit hakea tietyllä aikavälillä luotuja tai päivittyneitä tilauksia käyttämällä seuraavia tilausrajapinnan parametreja:
    • /api/v0/orders?created_at-from={timestamp}
    • /api/v0/orders?updated_at-from={timestamp}
  • GET /webhooks/changes?order_ids={orderIds}: Hakee listan tilauksista ID-numeroiden perusteella.

    Korvaava toiminto: Usean tilauksen hakeminen yhdellä kutsulla ID-tunnisteiden perusteella ei ole mahdollista millään yksittäisellä MyCashflow API:n toiminnolla, mutta voit hakea listan tilauksia yksitellen käyttämällä GET /api/v0/orders/{orderId} -kutsua.

  • GET /webhooks/send: Lähettää Webhook-sanoman uudestaan (esimerkiksi jos se epäonnistui aiemmin).

    Korvaava toiminto: Uusi Webhooks-toteutus ei sisällä valmista toimintoa Webhook-sanoman uudelleenlähettämiselle, mutta sanoman lähetyksen epäonnistuessa uusi Webhooks yrittää automaattisesti lähettää sanoman uudelleen 15 kertaa: ensimmäisen kerran 15s kuluttua ja uudestaan kaksinkertaisen ajan kuluessa (aikaväli tuplautuu jokaisella yrityksellä).