Skip to content
Wink

Integracija Webhookov

Webhooki omogočajo vašim sistemom prejemanje obvestil v realnem času, ko se na vašem Wink računu zgodijo dogodki — nove rezervacije, odpovedi, posodobitve plačil in še več. Ta vodič vas vodi skozi nastavitev in najboljše prakse.

Ciljna publika

Section titled “Ciljna publika”

Ta vodič je namenjen razvijalcem, ki integrirajo Wink z zunanjimi sistemi, kot so sistemi za upravljanje nepremičnin (PMS), upravljalci kanalov, CRM-ji ali prilagojene nadzorne plošče.

Kako webhooki delujejo

Section titled “Kako webhooki delujejo”
  1. Registrirate URL webhooka na Wink.
  2. Ko se zgodi dogodek (npr. nova rezervacija), Wink pošlje HTTP POST na vaš URL.
  3. Vaš strežnik obdela vsebino in odgovori z 200 OK.

Nastavitev webhooka

Section titled “Nastavitev webhooka”
  1. Prijavite se v svoj račun (Extranet, Studio ali TripPay — vsi podpirajo webhooke).
  2. Pojdite na Applications in nato Webhooks. Oglejte si Webhooks.
  3. Kliknite Create webhook.
  4. Vnesite ime (npr. “PMS Sinhronizacija rezervacij”).
  5. Vnesite svoj webhook URL — HTTPS končno točko na vašem strežniku.
  6. Izberite dogodke — Izberite specifične dogodke, na katere se želite naročiti, ali pustite prazno, da prejmete vse dogodke.
  7. Vklopite Enabled.
  8. Kliknite Save — odgovor prikaže vaš signing secret samo enkrat; shranite ga zdaj.

Vrste dogodkov

Section titled “Vrste dogodkov”

Wink danes objavlja 70 vrst webhook dogodkov, ki zajemajo rezervacije, nepremičnine, račune (upravljavske entitete) in inventar (vrste sob, cenovne načrte, glavne cene, dodatke, objekte, prodajne kanale, promocije). Pogosti so:

KategorijaPrimeri
Rezervacijabooking.create, booking.cancelled, booking.refund.partial, booking.refund.full, booking.review.created
Nepremičninaproperty.created, property.status.updated, property.policy.updated
Inventarroom_type.updated, rate_plan.created, master_rate.updated, special_rate.created, sales_channel.created
Računmanaging_entity.created, managing_entity.status.updated, managing_entity.manager.added

Celoten, generiran seznam — z opisom, kdo ga prejme, in povezavo do referenčne strani vsakega dogodka — je Katalog webhook dogodkov. Referenčna stran za vsak dogodek (JSON telo, glave, politika ponovnih poskusov) je na voljo v Webhooks API.

Ogled vseh vrst dogodkov

Kaj prejmete

Section titled “Kaj prejmete”

Vsaka dostava je HTTP POST na vaš webhook URL z Content-Type: application/json in to ovojnino:

{
  "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": { "...": "dogodkovno-specifična vsebina, npr. BookingWebhookPayload" }
}
  • id — identifikator dogodka; enak za vsako končno točko vašega računa, ki prejme ta dogodek, in za vsak ponovni poskus. Uporabite ga kot svojo ključ idempotentnosti.
  • type — ključ vrste dogodka (tudi poslan kot glava Wink-Event-Type). Razločite po type in schemaVersion za razčlenitev object.
  • object — skrbno izbran povzetek vira, na katerega se dogodek nanaša (identifikatorji, status, polja, na katera vplivate) plus links.self, kanonični REST URL dobaviteljeve strani celotnega vira. Pridobite ga z lastnimi API poverilnicami, ko potrebujete več kot povzetek; če dogodek prejmete kot preprodajalec ali potovalni agent, uporabite ustrezno končno točko svojega API-ja za isti identifikator.

Vsaka shema vsebine je dokumentirana za vsak dogodek v referenci Webhooks API.

Glave

Section titled “Glave”
GlavaPomen
Wink-VersionVerzija žične pogodbe, 2.0.
Wink-Event-IdEnako kot id v telesu — vaš ključ idempotentnosti.
Wink-Delivery-IdEdinstven za vsako končno točko za dogodek; se spremeni le, če ponovno dostavite.
Wink-Event-TypeEnako kot type v telesu.
Wink-Delivery-AttemptŠtevilka poskusa dostave, štetje od 1.
Wink-SignatureHMAC podpis — glej spodaj.

Preverjanje podpisov

Section titled “Preverjanje podpisov”

Vsak webhook ima signing secret (whsec_…), ki ga Wink prikaže samo enkrat, ko ustvarite webhook ali zamenjate njegov skrivni ključ. Shranite ga kot geslo. Vsaka dostava nosi

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

kjer je t Unix časovni žig (v sekundah) in v1 je hex niz male črke HMAC-SHA256 niza t + "." + rawBody, podpisan s skrivnostjo, rawBody pa je natančno telo zahteve, kot je prejeto — ne serializirajte JSON-a znova pred preverjanjem. 24 ur po zamenjavi skrivnosti glava nosi drugo vrednost v1=, podpisano s prejšnjo skrivnostjo; sprejmite dostavo, če se katerikoli v1 ujema.

Preverite v štirih korakih: razčlenite t in vsak v1; ponovno izračunajte HMAC nad t.rawBody s svojo skrivnostjo; primerjajte s primerjavo v konstantnem času; zavrnite, če je |now − t| večji od vaše tolerance (priporočeno 5 minut).

// Node.js (Express stil; poskrbite, da imate RAW telo, ne razčlenjenega objekta)
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)));
}

Skrivnost zamenjajte iz portala ali z POST /api/managing-entity/{id}/webhook/{webhookId}/rotate-secret; odgovor prikaže novo skrivnost samo enkrat, stara pa ostane veljavna 24 ur, medtem ko jo uvajate.

Ponovni poskusi in ponovna dostava

Section titled “Ponovni poskusi in ponovna dostava”
  • Odgovorite z vsakim 2xx v 10 sekundah, da potrdite prejem. Težka opravila izvajajte asinhrono.
  • 5xx, timeout, 408 ali 429 se poskušajo znova z vračanjem: po 1 minuti, 5 minutah, 30 minutah, 2 urah, 6 urah, 12 urah, nato dnevno — 10 poskusov v približno 3 dneh — nato je dostava označena kot mrtva.
  • Vsak drug 4xx se obravnava kot “zavrnjena dostava” in se ne poskuša znova.
  • Vsak dogodek, dostava in poskus (status, izsek odgovora) je viden pod Applications > Webhooks in preko API-ja (…/webhook/event/grid, …/webhook/delivery/grid). Lahko ponovno dostavite katerokoli dostavo (POST …/webhook/delivery/{deliveryId}/redeliver, kar začne nov niz poskusov), ponovno dostavite vse mrtve dostave webhooka naenkrat (POST …/webhook/{webhookId}/redeliver-dead), ali prekličete eno.
  • Dostave se hranijo 30 dni.

Testni dogodki

Section titled “Testni dogodki”

Pošljite si sintetični dogodek webhook.test iz portala ali z POST /api/managing-entity/{id}/webhook/{webhookId}/test. Podpisan je in dostavljen enako kot pravi dogodek, tako da lahko preverite svojo končno točko, preverjanje podpisa in obravnavo idempotentnosti pred naročitvijo na žive dogodke.

Najboljše prakse

Section titled “Najboljše prakse”
  • Uporabljajte HTTPS — Wink pošilja vsebine samo na HTTPS končne točke.
  • Odgovarjajte hitro — Vrnete 200 OK takoj, ko prejmete vsebino. Vsa težka obdelava naj bo asinhrona.
  • Idempotentnost — Vaš obdelovalec naj bo idempotenten; odstranjujte podvojene po Wink-Event-Id. Wink ponavlja, če ne prejme 2xx odgovora.
  • Preverite vir — Pred obdelavo preverite glavo Wink-Signature (glej Preverjanje podpisov); zavrnite vse, kar ne uspe.
  • Dnevnik — Beležite vsak webhook payload, ki ga prejmete. To močno olajša odpravljanje težav pri integraciji.

Zaustavitev in brisanje

Section titled “Zaustavitev in brisanje”

Webhook lahko onemogočite brez brisanja. To začasno ustavi dostavo, da lahko odpravljate težave brez izgube nastavitve. Ko ste pripravljeni, ga ponovno vklopite.

Brisanje webhooka ga trajno odstrani. Vsaka integracija, ki je odvisna od tega webhooka, bo prenehala prejemati obvestila.

Dodatno branje

Section titled “Dodatno branje”