Siirry sisältöön
Wink

Webhook-integraatio

Webhookit mahdollistavat järjestelmiesi vastaanottaa reaaliaikaisia ilmoituksia, kun tapahtumia tapahtuu Wink-tililläsi — uusia varauksia, peruutuksia, maksupäivityksiä ja muuta. Tämä opas ohjaa sinut asennuksen ja parhaiden käytäntöjen läpi.

Kohdeyleisö

Osio nimeltä “Kohdeyleisö”

Tämä opas on tarkoitettu kehittäjille, jotka integroivat Winkia ulkoisiin järjestelmiin, kuten kiinteistöhallintajärjestelmiin (PMS), kanavahallintaan, CRM-järjestelmiin tai mukautettuihin hallintapaneeleihin.

Miten webhookit toimivat

Osio nimeltä “Miten webhookit toimivat”
  1. Rekisteröit webhook-URL-osoitteen Winkissä.
  2. Kun tapahtuma tapahtuu (esim. uusi varaus), Wink lähettää HTTP POST -pyynnön URL-osoitteeseesi.
  3. Palvelimesi käsittelee tiedot ja vastaa 200 OK.

Webhookin asennus

Osio nimeltä “Webhookin asennus”
  1. Kirjaudu tilillesi (Extranet, Studio tai TripPay — kaikki tukevat webhookeja).
  2. Siirry kohtaan Applications ja sitten Webhooks. Katso Webhooks.
  3. Klikkaa Create webhook.
  4. Anna nimi (esim. “PMS Booking Sync”).
  5. Syötä webhook-URL — HTTPS-päätepiste palvelimellasi.
  6. Valitse tapahtumat — Valitse tilattavat tapahtumat tai jätä tyhjäksi vastaanottaaksesi kaikki tapahtumat.
  7. Kytke Enabled päälle.
  8. Klikkaa Save — vastaus näyttää allekirjoitussalaisuuden kerran; tallenna se nyt.

Tapahtumatyypit

Osio nimeltä “Tapahtumatyypit”

Wink julkaisee tänään 70 webhook-tapahtumatyyppiä varauksiin, kiinteistöihin, tileihin (hallinnoivat tahot) ja inventaarioon (huonetyypit, hintasuunnitelmat, päähinnat, lisäpalvelut, tilat, myyntikanavat, kampanjat) liittyen. Yleisiä:

KategoriaEsimerkkejä
Varausbooking.create, booking.cancelled, booking.refund.partial, booking.refund.full, booking.review.created
Kiinteistöproperty.created, property.status.updated, property.policy.updated
Inventaarioroom_type.updated, rate_plan.created, master_rate.updated, special_rate.created, sales_channel.created
Tilimanaging_entity.created, managing_entity.status.updated, managing_entity.manager.added

Täydellinen, generoitu lista — kuvauksineen, vastaanottajineen ja linkkeineen kunkin tapahtuman viitesivulle — on Webhook Events Catalog. Jokaisen tapahtuman viitesivu (JSON-rakenne, otsikot, uudelleenyrityskäytäntö) löytyy Webhooks API.

Näytä kaikki tapahtumatyypit

Mitä vastaanotat

Osio nimeltä “Mitä vastaanotat”

Jokainen toimitus on HTTP POST webhook-URL-osoitteeseesi Content-Type: application/json -otsikolla ja seuraavalla kuorella:

{
  "id": "0198a4f2-6b0e-7c1d-9a3e-2f4b8c6d1e0a",
  "type": "booking.create",
  "occurredAt": "2026-08-15T09:30:00Z",
  "ownerIdentifier": "3c6b1a5d-8e2f-4a0b-9c7d-6e4f0a8b2c51",
  "recipientRole": "SUPPLIER",
  "schemaVersion": 2,
  "object": { "...": "tapahtumakohtainen data, esim. BookingWebhookPayload" }
}
  • id — tapahtuman tunniste; sama kaikille tilisi päätepisteille, jotka vastaanottavat tämän tapahtuman, ja kaikille uudelleenyrityksille. Käytä sitä idempotenssiavaimena.
  • type — tapahtumatyyppinäppäin (lähetetään myös Wink-Event-Type-otsikkona). Haarauta type ja schemaVersion perusteella object-kentän jäsentämiseen.
  • object — kuratoitu yhteenveto resurssista, johon tapahtuma liittyy (tunnisteet, tila, käsiteltävät kentät) sekä links.self, toimittajan puolen kanoninen REST-URL koko resurssille. Hae se omilla API-tunnuksillasi, kun tarvitset enemmän kuin yhteenvedon; jos saat tapahtuman jälleenmyyjänä tai matkatoimistona, käytä vastaavaa resurssipäätepistettä omassa API-pinnassasi saman tunnisteen perusteella.

Jokaisen kuoren skeema on dokumentoitu tapahtumakohtaisesti Webhooks API -viitteessä.

Otsikot

Osio nimeltä “Otsikot”
OtsikkoMerkitys
Wink-VersionRajapintasopimuksen versio, 2.0.
Wink-Event-IdSama kuin id rungossa — idempotenssiavain.
Wink-Delivery-IdYksilöllinen päätepistettä kohden per tapahtuma; muuttuu vain uudelleenlähetyksessä.
Wink-Event-TypeSama kuin type rungossa.
Wink-Delivery-Attempt1-pohjainen yrityskertojen numero tälle toimitukselle.
Wink-SignatureHMAC-allekirjoitus — katso alla.

Allekirjoitusten varmistaminen

Osio nimeltä “Allekirjoitusten varmistaminen”

Jokaisella webhookilla on allekirjoitussalaisuus (whsec_…), jonka Wink näyttää vain kerran, kun luot webhookin tai kierrät sen salaisuuden. Tallenna se kuin salasana. Jokainen toimitus sisältää

Wink-Signature: t=1755250200,v1=5d41402abc4b2a76b9719d911017c592…

missä t on Unix-aikaleima (sekunteina) ja v1 on pienaakkosilla kirjoitettu hex-muotoinen HMAC-SHA256 merkkijonosta t + "." + rawBody, avaimena salaisuutesi, ja rawBody on tarkka pyyntörunko tavuina sellaisena kuin se vastaanotetaan — älä uudelleensarjoita JSON:ia ennen varmistusta. 24 tuntia salaisuuden kierron jälkeen otsikko sisältää toisen v1= arvon, joka on allekirjoitettu edellisellä salaisuudella; hyväksy toimitus, jos jokin v1 vastaa.

Varmista neljässä vaiheessa: jäsennä t ja kaikki v1; laske HMAC uudelleen t.rawBody-merkkijonolle salaisuudellasi; vertaa vakioaikaisella vertailulla; hylkää, jos |nyt − t| ylittää sallitun rajan (suositus 5 minuuttia).

// Node.js (Express-tyylinen; varmista, että sinulla on RAW-runko, ei jäsennelty objekti)
import { createHmac, timingSafeEqual } from 'node:crypto';


export function verifyWinkSignature(header, rawBody, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=').map((s) => s.trim())));
  const t = Number(parts.t);
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return header
    .split(',')
    .filter((p) => p.trim().startsWith('v1='))
    .map((p) => p.trim().slice(3))
    .some((v1) => v1.length === expected.length && timingSafeEqual(Buffer.from(v1, 'utf8'), Buffer.from(expected, 'utf8')));
}
// Java
static boolean verify(String header, String rawBody, String secret, long nowSeconds, long toleranceSeconds) throws Exception {
    long t = Long.MIN_VALUE;
    List<String> signatures = new ArrayList<>();
    for (String part : header.split(",")) {
        String[] kv = part.trim().split("=", 2);
        if (kv[0].equals("t")) t = Long.parseLong(kv[1]);
        else if (kv[0].equals("v1")) signatures.add(kv[1]);
    }
    if (t == Long.MIN_VALUE || Math.abs(nowSeconds - t) > toleranceSeconds) return false;
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    byte[] expected = HexFormat.of().formatHex(mac.doFinal((t + "." + rawBody).getBytes(StandardCharsets.UTF_8))).getBytes(StandardCharsets.US_ASCII);
    return signatures.stream().anyMatch(v1 -> MessageDigest.isEqual(expected, v1.toLowerCase().getBytes(StandardCharsets.US_ASCII)));
}

Kierrä salaisuus portaalista tai POST /api/managing-entity/{id}/webhook/{webhookId}/rotate-secret -kutsulla; vastaus näyttää uuden salaisuuden kerran, ja vanha toimii vielä 24 tuntia käyttöönoton aikana.

Uudelleenyritykset ja uudelleenlähetykset

Osio nimeltä “Uudelleenyritykset ja uudelleenlähetykset”
  • Vastaa millä tahansa 2xx-vastauksella 10 sekunnin sisällä kuittaaksesi. Tee raskas käsittely asynkronisesti.
  • 5xx, aikakatkaisu, 408 tai 429 yritetään uudelleen viivein: 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, sitten päivittäin — 10 yritystä noin 3 päivän aikana — jonka jälkeen toimitus merkitään kuolleeksi.
  • Muut 4xx-vastaukset käsitellään “hylkäsit tämän toimituksen” -tapauksena, eikä niitä yritetä uudelleen.
  • Jokainen tapahtuma, toimitus ja yritys (tila, vastauskatkelma) näkyy Applications > Webhooks -kohdassa ja API:n kautta (…/webhook/event/grid, …/webhook/delivery/grid). Voit uudelleenlähettää minkä tahansa toimituksen (POST …/webhook/delivery/{deliveryId}/redeliver, joka aloittaa uuden yritysarjan), uudelleenlähettää kaikki kuolleet toimitukset yhdellä kertaa (POST …/webhook/{webhookId}/redeliver-dead) tai peruuttaa yhden.
  • Toimitukset säilytetään 30 päivää.

Testitapahtumat

Osio nimeltä “Testitapahtumat”

Lähetä itsellesi synteettinen webhook.test -tapahtuma portaalista tai POST /api/managing-entity/{id}/webhook/{webhookId}/test -kutsulla. Se on allekirjoitettu ja toimitetaan täsmälleen kuten oikea tapahtuma, joten voit varmistaa päätepisteesi, allekirjoituksen tarkistuksen ja idempotenssikäsittelyn ennen live-tapahtumiin tilaamista.

Parhaat käytännöt

Osio nimeltä “Parhaat käytännöt”
  • Käytä HTTPS:ää — Wink lähettää kuoret vain HTTPS-päätepisteisiin.
  • Vastaa nopeasti — Palauta 200 OK heti, kun saat kuoren. Tee raskas käsittely asynkronisesti.
  • Idempotenssi — Käsittelijäsi tulee olla idempotentti; poista duplikaatit Wink-Event-Id-kentän perusteella. Wink yrittää uudelleen, jos se ei saa 2xx-vastausta.
  • Varmista lähde — Tarkista Wink-Signature-otsikko (katso Allekirjoitusten varmistaminen) ennen käsittelyä; hylkää kaikki epäonnistuneet.
  • Lokitus — Kirjaa kaikki vastaanottamasi webhook-kuoret. Tämä helpottaa integrointiongelmien vianmääritystä.

Tauko ja poisto

Osio nimeltä “Tauko ja poisto”

Voit poistaa käytöstä webhookin poistamatta sitä. Tämä keskeyttää toimitukset, jotta voit vianmäärityksen aikana säilyttää asetukset. Kun olet valmis, kytke se takaisin päälle.

Webhookin poistaminen poistaa sen pysyvästi. Kaikki integraatiot, jotka käyttävät kyseistä webhookia, lakkaavat vastaanottamasta ilmoituksia.

Lisälukemista

Osio nimeltä “Lisälukemista”