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 daugiau. Š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 skydeliai.

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 į 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, pakartotinio siuntimo politika) yra Webhooks API dokumentacijoje.

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

Ką gaunate

Section titled “Ką gaunate”

Kiekvienas pranešimas yra HTTP POST į jūsų webhook URL su Content-Type: application/json ir šiuo apvalkalu:

{
  "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 kiekvienam pakartotiniam siuntimui. 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, gaukite jį su savo API kredencialais; 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 siunčiate iš naujo.
Wink-Event-TypeTas pats kaip type kūne.
Wink-Delivery-AttemptBandymo numeris, pradedant nuo 1, šiam siuntimui.
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 siuntimas turi

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

čia t yra Unix laiko žyma (sekundėmis), o v1 yra mažosiomis raidėmis užkoduotas heksadecimalus HMAC-SHA256 iš eilutės t + "." + rawBody, pasirašytas jūsų slaptuoju raktu, o rawBody yra tikslūs gauti užklausos kūno baitai — nepradėkite JSON iš naujo serializuoti prieš tikrinimą. 24 valandas po rakto pakeitimo antraštėje yra antras v1= parašas, pasirašytas su ankstesniu raktu; priimkite siuntimą, 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 saugų palyginimą; atminkite, jei |dabar − t| viršija jūsų toleranciją (rekomenduojama 5 minutės).

// 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 persiuntimas

Section titled “Pakartotiniai bandymai ir persiuntimas”
  • Atsakykite bet kuriuo 2xx per 10 sekundžių, kad patvirtintumėte gavimą. Sunkų darbą atlikite asinchroniškai.
  • 5xx, laiko išeiga, 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 siuntimas pažymimas kaip miręs.
  • Bet kuris kitas 4xx laikomas, kad jūs atmetėte šį siuntimą, ir nebebus bandomas pakartotinai.
  • Kiekvienas įvykis, siuntimas ir bandymas (būsena, atsakymo fragmentas) matomas skiltyje Applications > Webhooks ir per API (…/webhook/event/grid, …/webhook/delivery/grid). Galite persiųsti bet kurį siuntimą (POST …/webhook/delivery/{deliveryId}/redeliver, kuris pradeda naują bandymų seriją), persiųsti visus mirusius webhook’o siuntimus vienu metu (POST …/webhook/{webhookId}/redeliver-dead), arba atšaukti vieną.
  • Siuntimai 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; deduplikacija pagal Wink-Event-Id. Wink bando pakartotinai, jei negauna 2xx atsakymo.
  • Patikrinkite šaltinį — Patikrinkite Wink-Signature antraštę (žr. Parašų tikrinimas) prieš apdorojimą; atminkite viską, kas nepraeina.
  • Registravimas — Registruokite kiekvieną gautą webhook duomenų paketą. Tai labai palengvina integracijos klaidų taisymą.

Sustabdymas ir ištrynimas

Section titled “Sustabdymas ir ištrynimas”

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

Webhook’o ištrynimas jį pašalina visam laikui. Bet kuri integracija, priklausanti nuo to webhook’o, nustos gauti pranešimus.

Tolimesnė literatūra

Section titled “Tolimesnė literatūra”