
Asetukset > Integraatiot ja API

Asetukset > Integraatiot ja API > Webhookit
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
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 HTTPPOST, 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 ilmoitetaanapiVersion-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ä tahansa2xx-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.

Toimituksen tiedot — yritysten aikajana ja allekirjoitettu hyötykuorma
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.
Kaksoiskappaleiden karsinta
Sama tapahtuma voi saapua useammin kuin kerran, joten päätepisteesi on oltava idempotentti. Karsi kaksoiskappaleeteventId-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 onwhsec_. 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. 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 hallitaanhooks-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.