Skip to content
Wink

Webhook integracija

Webhook’ai leidžia jūsų sistemoms gauti realaus laiko pranešimus, kai jūsų Wink paskyroje įvyksta įvykiai — nauji užsakymai, atšaukimai, mokėjimų atnaujinimai ir kt. Šis vadovas padės jums nustatyti webhook’us ir pateiks geriausias praktikas.

Auditorija

Section titled “Auditorija”

Šis vadovas skirtas kūrėjams, integruojantiems Wink su išorinėmis sistemomis, tokiomis kaip turto valdymo sistemos (PMS), kanalų valdytojai, CRM ar individualios valdymo panelės.

Kaip veikia webhook’ai

Section titled “Kaip veikia webhook’ai”
  1. Užregistruojate webhook URL Wink sistemoje.
  2. Kai įvyksta įvykis (pvz., naujas užsakymas), Wink siunčia HTTP POST užklausą į jūsų URL.
  3. Jūsų serveris apdoroja duomenis ir atsako su 200 OK.

Webhook’o nustatymas

Section titled “Webhook’o nustatymas”
  1. Prisijunkite prie savo paskyros (Extranet, Studio arba TripPay — visi palaiko webhook’us).
  2. Eikite į Applications, tada Webhooks. Žr. Webhook’ai.
  3. Spustelėkite Create webhook.
  4. Įveskite pavadinimą (pvz., “PMS užsakymų sinchronizavimas”).
  5. Įveskite savo webhook URL — HTTPS galinį tašką jūsų serveryje.
  6. Pasirinkite įvykius — Pasirinkite konkrečius įvykius, kuriuos norite prenumeruoti, arba palikite tuščią, kad gautumėte visus įvykius.
  7. Įjunkite Enabled.
  8. Spustelėkite Save — atsakyme bus parodytas jūsų pasirašymo slaptasis raktas vieną kartą; išsaugokite jį dabar.

Įvykių tipai

Section titled “Įvykių tipai”

Šiandien Wink skelbia 70 webhook įvykių tipų, susijusių su užsakymais, turtais, paskyromis (valdančiomis įmonėmis) ir inventoriaus valdymu (kambarių tipai, kainų planai, pagrindinės kainos, papildiniai, patalpos, pardavimo kanalai, akcijos). Dažniausi:

KategorijaPavyzdžiai
Užsakymasbooking.create, booking.cancelled, booking.refund.partial, booking.refund.full, booking.review.created
Turtasproperty.created, property.status.updated, property.policy.updated
Inventoriusroom_type.updated, rate_plan.created, master_rate.updated, special_rate.created, sales_channel.created
Paskyramanaging_entity.created, managing_entity.status.updated, managing_entity.manager.added

Pilnas, sugeneruotas sąrašas — su aprašymu, kas jį gauna ir nuoroda į kiekvieno įvykio aprašymo puslapį — yra Webhook įvykių katalogas. Kiekvieno įvykio aprašymo puslapis (JSON turinys, antraštės, pakartojimo politika) yra Webhooks API dokumentacijoje.

Peržiūrėti visus įvykių tipus

Ką gaunate

Section titled “Ką gaunate”

Kiekvienas pranešimas yra HTTP POST užklausa į jūsų webhook URL su Content-Type: application/json ir tokia struktūra:

{
  "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": { "...": "įvykio specifinė informacija, pvz., BookingWebhookPayload" }
}
  • id — įvykio identifikatorius; tas pats visiems jūsų paskyros galiniams taškams, kurie gauna šį įvykį, ir visiems pakartojimams. Naudokite kaip idempotencijos raktą.
  • type — įvykio tipo raktas (taip pat siunčiamas kaip Wink-Event-Type antraštė). Remkitės type ir schemaVersion, kad išanalizuotumėte object.
  • object — atrinkta išteklių santrauka, apie kurią yra įvykis (identifikatoriai, būsena, laukai, su kuriais dirbate), taip pat links.self — tiekėjo pusės kanoninis REST URL pilnam ištekliui. Jei reikia daugiau nei santrauka, naudokite savo API kredencialus, kad gautumėte pilną informaciją; jei gaunate įvykį kaip perpardavėjas ar kelionių agentas, naudokite atitinkamą savo API išteklių galinį tašką su tuo pačiu identifikatoriumi.

Kiekvieno duomenų formato aprašymas yra dokumentuotas kiekvienam įvykiui Webhooks API dokumentacijoje.

Antraštės

Section titled “Antraštės”
AntraštėReikšmė
Wink-VersionRyšio sutarties versija, 2.0.
Wink-Event-IdTas pats kaip id kūne — jūsų idempotencijos raktas.
Wink-Delivery-IdUnikalus kiekvienam galiniam taškui ir įvykiui; keičiasi tik jei pakartotinai siunčiate.
Wink-Event-TypeTas pats kaip type kūne.
Wink-Delivery-AttemptBandymo numeris, pradedant nuo 1, šiam pristatymui.
Wink-SignatureHMAC parašas — žr. žemiau.

Parašų tikrinimas

Section titled “Parašų tikrinimas”

Kiekvienas webhook’as turi pasirašymo slaptą raktą (whsec_…), kurį Wink parodo vieną kartą, kai sukuriate webhook’ą arba pakeičiate jo raktą. Išsaugokite jį kaip slaptažodį. Kiekvienas pristatymas turi

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

čia t yra Unix laiko žyma (sekundėmis), o v1 yra mažosiomis raidėmis užrašytas heksadecimalus HMAC-SHA256 parašas iš eilutės t + "." + rawBody, pasirašytas jūsų slaptuoju raktu, o rawBody yra tikslūs gautos užklausos kūno baitai — neprikurkite JSON iš naujo prieš tikrinimą. 24 valandas po rakto pakeitimo antraštėje gali būti antras v1= parašas, pasirašytas senuoju raktu; priimkite pristatymą, jei bet kuris v1 sutampa.

Patikrinkite keturiais žingsniais: išanalizuokite t ir kiekvieną v1; perskaičiuokite HMAC per t.rawBody su savo raktu; palyginkite naudojant laiko atžvilgiu saugų palyginimą; atminkite, kad jei |dabar − t| viršija jūsų toleranciją (rekomenduojama 5 minutės), atminkite.

// Node.js (Express stilius; įsitikinkite, kad turite RAW kūną, o ne išanalizuotą objektą)
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)));
}

Pakeiskite raktą portale arba naudodami POST /api/managing-entity/{id}/webhook/{webhookId}/rotate-secret; atsakyme bus parodytas naujas raktas vieną kartą, o senasis galios dar 24 valandas, kol jį išplatinsite.

Pakartotiniai bandymai ir pakartotinis pristatymas

Section titled “Pakartotiniai bandymai ir pakartotinis pristatymas”
  • Atsakykite bet kuriuo 2xx per 10 sekundžių, kad patvirtintumėte gavimą. Sunkų darbą atlikite asinchroniškai.
  • 5xx, timeout’as, 408 arba 429 bus bandomi pakartotinai su atidėjimu: po 1 minutės, 5 minučių, 30 minučių, 2 valandų, 6 valandų, 12 valandų, tada kasdien — 10 bandymų per maždaug 3 dienas — po to pristatymas pažymimas kaip miręs.
  • Bet kuris kitas 4xx laikomas kaip “jūs atmetėte šį pristatymą” ir nebebus bandomas pakartotinai.
  • Kiekvienas įvykis, pristatymas ir bandymas (būsena, atsakymo fragmentas) matomas skiltyje Applications > Webhooks ir per API (…/webhook/event/grid, …/webhook/delivery/grid). Galite pakartotinai pristatyti bet kurį pristatymą (POST …/webhook/delivery/{deliveryId}/redeliver, kuris pradeda naują bandymų seriją), pakartotinai pristatyti visus mirusius webhook’o pristatymus vienu metu (POST …/webhook/{webhookId}/redeliver-dead), arba atšaukti vieną.
  • Pristatymų duomenys saugomi 30 dienų.

Testiniai įvykiai

Section titled “Testiniai įvykiai”

Išsiųskite sau sintetinius webhook.test įvykius iš portalo arba naudodami POST /api/managing-entity/{id}/webhook/{webhookId}/test. Jie pasirašyti ir pristatomi taip pat kaip tikri įvykiai, todėl galite patikrinti savo galinį tašką, parašo tikrinimą ir idempotencijos valdymą prieš prenumeruodami gyvus įvykius.

Geriausios praktikos

Section titled “Geriausios praktikos”
  • Naudokite HTTPS — Wink siunčia duomenis tik į HTTPS galinius taškus.
  • Atsakykite greitai — Grąžinkite 200 OK iš karto gavę duomenis. Sunkų apdorojimą atlikite asinchroniškai.
  • Idempotencija — Jūsų apdorojimo funkcija turi būti idempotentiška; pašalinkite dubliatus pagal Wink-Event-Id. Wink bando pakartoti, jei negauna 2xx atsakymo.
  • Patikrinkite šaltinį — Patikrinkite Wink-Signature antraštę (žr. Parašų tikrinimas) prieš apdorojimą; atminkite viską, kas nepraeina patikros.
  • Registravimas — Užfiksuokite kiekvieną gautą webhook duomenų paketą. Tai labai palengvina integracijos problemų sprendimą.

Sustabdymas ir ištrynimas

Section titled “Sustabdymas ir ištrynimas”

Galite išjungti webhook’ą, jo neištrindami. Tai sustabdo pristatymą, kad galėtumėte spręsti problemas neprarandant konfigūracijos. Kai būsite pasiruošę, vėl įjunkite.

Ištrynus webhook’ą, jis pašalinamas visam laikui. Bet kuri integracija, priklausanti nuo to webhook’o, nustos gauti pranešimus.

Tolimesnė literatūra

Section titled “Tolimesnė literatūra”