Skip to main content
Webhookien määritys integraatioasetuksissa

Asetukset > Integraatiot ja API

Webhook-taulukko, jossa tapahtuma, URL, status, luontipäivä ja rivin toimintovalikko auki

Asetukset > Integraatiot ja API > Webhookit

Webhookit ilmoittavat järjestelmällesi, kun tilaus muuttuu TWICE Commercessa. Kun tapahtuma laukeaa, TWICE lähettää HTTP POST -pyynnön rekisteröimääsi URL-osoitteeseen, joten voit reagoida ilman API:n kyselyä.

Tapahtumatyypit

TWICE lähettää kolme tilaustapahtumaa: Hyötykuorman data sisältää kyseessä olevan tilauksen. Resursseja ja tapahtumia voidaan lisätä myöhemmin.

Mikä laukaisee tapahtuman order.updated

order.updated laukeaa, kun tilaus itse muuttuu ja kun jokin sen alatieto muuttuu:
  • Rivitiedot
  • Varastoartikkelit
  • Asiakkaat
  • Kommentit
  • Tunnisteet
  • Dokumentit
  • Alennukset
  • Attribuutit
  • Kassan kentät
Maksutietueet eivät kuulu tähän joukkoon — maksun kirjoittaminen ei itsessään laukaise tapahtumaa order.updated. Yksi operaatio, joka koskee useaa alariviä (esimerkiksi joukkomuokkaus, joka päivittää tilauksen ja useita rivitietoja samassa transaktiossa), tuottaa yhden toimituksen, ei montaa. TWICE yhdistää nopeasti peräkkäiset muutokset tilauskohtaisesti, joten päätepisteesi saa yhden koostetun tapahtuman.
Odottavien tilausten (kesken olevien kassaluonnosten) vaimennus koskee vain luontia: odottavan tilauksen tallentaminen ei lähetä mitään, ja order.created laukeaa, kun tilaus poistuu odottavasta statuksesta. Odottavan tilauksen päivitykset lähettävät silti tapahtuman order.updated, ja poistaminen lähettää tapahtuman order.deleted.

Miten se toimii

Jokainen toimitus on HTTP POST, jonka JSON-runko on tapahtumaa kuvaava kuori. Kyseessä oleva resurssi kulkee data-kentässä:
string
Tapahtuman yksilöivä tunnus. Lähetetään myös X-Twice-Event-Id -otsakkeessa. Tee kaksoiskappaleiden karsinta tämän arvon perusteella.
string
Laukennut tapahtuma, esimerkiksi order.created. Yksi webhook vastaanottaa yhtä tapahtumatyyppiä.
string
ISO 8601 -aikaleima siitä, milloin tapahtuma sattui.
string
Resurssi, jota tapahtuma koskee, esimerkiksi order.
string
Kyseessä olevan resurssin tunnus.
string
API-versio, jonka mukaisena hyötykuorma muodostetaan.
object | null
Resurssi samassa muodossa kuin REST API sen palauttaa. null tapahtumalle order.deleted.
data-kentän sisältämä Order-skeema on kuvattu API-viitteessä.

API-version kiinnitys

Jokainen webhook on kiinnitetty siihen API-versioon, joka oli uusin sen luontihetkellä, ja versio ilmoitetaan apiVersion-kentässä. Uusi API-versio ei koskaan muuta jo vastaanottamaasi hyötykuorman muotoa — webhookin siirtäminen uudempaan versioon on erillinen päivitys.

Webhookien hallinta

Hallitse webhookeja kohdassa Asetukset → Integraatiot ja API → Webhookit. Luo webhook valitsemalla tapahtumatyyppi ja syöttämällä päätepisteen URL, joka vastaanottaa POST-pyynnön. Kohde-URL-osoitteiden on oltava HTTPS-osoitteita. Taulukossa näkyy kustakin webhookista: Loput löytyvät rivin toiminnoista: Näytä toimitukset, Ota käyttöön / Poista käytöstä, Näytä allekirjoitusavain ja Poista. Sama tapahtuma voidaan toimittaa useaan webhookiin — esimerkiksi yksi order.created-webhook CRM-järjestelmääsi ja toinen kirjanpitojärjestelmääsi.
Webhookit edellyttävät niitä sisältävää pakettia — muut tilit näkevät päivityskehotteen integraatioasetuksissa. Katso paketit.

Toimitus ja uudelleenyritykset

TWICE toimittaa webhookit asynkronisesti Cloud Tasks -jonon kautta. Toimitus onnistuu millä tahansa 2xx-vastauksella; mikä tahansa muu status — tai aikakatkaisu — lasketaan epäonnistuneeksi yritykseksi. Epäonnistunut toimitus yritetään uudelleen enintään 3 kertaa (yhteensä 4 yritystä), noin 10 s, 20 s ja 40 s edellisen yrityksen jälkeen, ja uudelleenyritykset päättyvät 10 minuuttia ensimmäisen yrityksen jälkeen. Kun 3 peräkkäistä tapahtumaa on käyttänyt kaikki yrityksensä, webhook poistetaan automaattisesti käytöstä syyllä TOO_MANY_FAILED_DELIVERY_ATTEMPTS, ja otat sen takaisin käyttöön käsin, kun päätepisteesi on jälleen tavoitettavissa. Käyttöönotto — tai webhookin osoittaminen toiseen URL-osoitteeseen — aloittaa uuden virheikkunan. Vastaa 2xx nopeasti. Jos käsittely on hidasta, kuittaa ensin ja siirrä työ jonoon.

Toimitusloki

Jokainen lähetetty toimitus tallennetaan. Näet ne webhookin Näytä toimitukset -toiminnolla osoitteessa /settings/connect/integrations/webhooks/{webhookId}. Lokia voi suodattaa ja järjestää tuloksen, tapahtuman, tapahtumatunnuksen, laukaisuajan, yritysten määrän ja viimeisimmän vastauksen mukaan.
Toimitusloki, jossa toimituksen tietopaneeli auki näyttäen yritysten aikajanan ja hyötykuorman

Toimituksen tiedot — yritysten aikajana ja allekirjoitettu hyötykuorma

Toimituksella on yksi neljästä statuksesta: Avaamalla rivin näet toimituksen tiedot: tapahtumatunnuksen, laukaisuajan, yritysten määrän ja viimeisimmän vastauksen, yritysten aikajanan kunkin yrityksen lopputuloksineen sekä täsmällisen lähetetyn hyötykuorman. Sieltä voit valita Kopioi payload tai Lähetä uudelleen, joka lähettää saman tallennetun hyötykuorman kohde-URL-osoitteeseen uudelleen.
Toimitukset, jotka on kirjattu ennen kuin toimitusloki tallensi hyötykuormia, eivät näytä hyötykuormaa eikä niitä voi lähettää uudelleen.
Testitoimitusta ei ole. Jos haluat kokeilla päätepistettä ennen tuotantoliikenteen ohjaamista siihen, luo webhook väliaikaiseen URL-osoitteeseen (luontidialogi ehdottaa palvelua webhook.site) ja laukaise tapahtuma.

Kaksoiskappaleiden karsinta

Sama tapahtuma voi saapua useammin kuin kerran, joten päätepisteesi on oltava idempotentti. Karsi kaksoiskappaleet eventId-arvon perusteella — se lähetetään sekä rungossa että X-Twice-Event-Id -otsakkeessa. Myöskään järjestystä ei taata. Kun järjestyksellä on merkitystä, vertaa eventTime-arvoja tai hae resurssin nykytila uudelleen API:n kautta.

Allekirjoitusten varmennus

Jokaisella webhookilla on allekirjoitusavain, jonka etuliite on whsec_. TWICE allekirjoittaa sillä jokaisen toimituksen ja lähettää allekirjoituksen X-Twice-Signature -otsakkeessa muodossa sha256=<hex> — se on HMAC-SHA256 täsmällisestä raa’asta pyyntörungosta. Varmenna raakojen runkotavujen perusteella ja jäsennä JSON vasta, kun allekirjoitus on todettu oikeaksi:

Allekirjoitusavaimen hallinta

Webhookin Näytä allekirjoitusavain -toiminnolla näytät, kopioit tai kierrätät avaimen.
Kierrättäminen korvaa avaimen välittömästi — toimitukset allekirjoitetaan siitä hetkestä alkaen uudella avaimella, joten päivitä päätepisteesi samaan aikaan.
Ennen allekirjoitusten käyttöönottoa luoduilla webhookeilla ei ole allekirjoitusavainta, ja niiden toimitukset pysyvät allekirjoittamattomina, kunnes luot sellaisen. Dialogi tarjoaa niille toiminnon Luo avain.

Kehittäjän viitetiedot

Webhookeja hallitaan hooks-päätepisteillä.

API: Webhooks

Avaa päätepiste API-viitteessä.

Aiheeseen liittyvät

Integraatiot

Webhookit API-avainten rinnalla.

API-avaimet

Tunnistaudu API:iin.

Tapahtumalokit

Jäljitysketju, jota vasten voit täsmäyttää.

Tilauksen elinkaari

Milloin tilaustapahtumat laukeavat.