Pāriet uz saturu
Wink

Webhook integrācija

Webhook ļauj jūsu sistēmām saņemt reāllaika paziņojumus, kad jūsu Wink kontā notiek notikumi — jaunas rezervācijas, atcelšanas, maksājumu atjauninājumi un citi. Šī rokasgrāmata soli pa solim ved cauri iestatīšanai un labākajām praksēm.

Auditorija

Section titled “Auditorija”

Šī rokasgrāmata ir paredzēta izstrādātājiem, kas integrē Wink ar ārējām sistēmām, piemēram, īpašumu pārvaldības sistēmām (PMS), kanālu pārvaldniekiem, CRM vai pielāgotām informācijas paneļiem.

Kā darbojas webhook

Section titled “Kā darbojas webhook”
  1. Jūs reģistrējat webhook URL Wink.
  2. Kad notiek notikums (piemēram, jauna rezervācija), Wink nosūta HTTP POST uz jūsu URL.
  3. Jūsu serveris apstrādā datus un atbild ar 200 OK.

Webhook iestatīšana

Section titled “Webhook iestatīšana”
  1. Piesakieties savā kontā (Extranet, Studio vai TripPay — visi atbalsta webhook).
  2. Dodieties uz Applications un pēc tam Webhooks. Skatīt Webhooks.
  3. Noklikšķiniet uz Create webhook.
  4. Ievadiet nosaukumu (piemēram, “PMS Booking Sync”).
  5. Ievadiet savu webhook URL — HTTPS galapunktu jūsu serverī.
  6. Izvēlieties notikumus — izvēlieties konkrētus notikumus, uz kuriem abonēties, vai atstājiet tukšu, lai saņemtu visus notikumus.
  7. Ieslēdziet Enabled.
  8. Noklikšķiniet uz Save — atbilde parāda jūsu parakstīšanas slepeno atslēgu vienu reizi; saglabājiet to tagad.

Notikumu veidi

Section titled “Notikumu veidi”

Wink šobrīd publicē 70 webhook notikumu veidus rezervācijām, īpašumiem, kontiem (pārvaldības vienībām) un inventāram (numuru veidi, tarifu plāni, galvenie tarifi, papildinājumi, ērtības, pārdošanas kanāli, akcijas). Biežākie:

KategorijaPiemēri
Rezervācijabooking.create, booking.cancelled, booking.refund.partial, booking.refund.full, booking.review.created
Īpašumsproperty.created, property.status.updated, property.policy.updated
Inventārsroom_type.updated, rate_plan.created, master_rate.updated, special_rate.created, sales_channel.created
Kontsmanaging_entity.created, managing_entity.status.updated, managing_entity.manager.added

Pilns, ģenerēts saraksts — ar aprakstu, kam tas tiek nosūtīts un saiti uz katra notikuma atsauces lapu — ir Webhook notikumu katalogs. Atsauces lapa katram notikumam (JSON saturs, galvenes, atkārtotas piegādes politika) atrodas Webhooks API.

Skatīt visus notikumu veidus

Ko jūs saņemat

Section titled “Ko jūs saņemat”

Katrs piegādes pieprasījums ir HTTP POST uz jūsu webhook URL ar Content-Type: application/json un šo aploksni:

{
  "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": { "...": "notikumam specifisks saturs, piemēram, BookingWebhookPayload" }
}
  • id — notikuma identifikators; identisks katram jūsu konta galapunktam, kas saņem šo notikumu, un katrai atkārtotai piegādei. Izmantojiet to kā savu idempotences atslēgu.
  • type — notikuma veida atslēga (tiek nosūtīta arī kā Wink-Event-Type galvene). Pamatojieties uz type un schemaVersion, lai parsētu object.
  • object — atlasīts resursa kopsavilkums, par kuru ir notikums (identifikatori, statuss, lauki, ar kuriem jūs strādājat) plus links.self, piegādātāja puses kanoniskais REST URL pilnam resursam. Iegūstiet to ar savām API akreditācijām, ja nepieciešams vairāk nekā kopsavilkums; ja saņemat notikumu kā izplatītājs vai ceļojumu aģents, izmantojiet atbilstošo sava API resursu galapunktu ar to pašu identifikatoru.

Katras piegādes shēmas dokumentācija ir pieejama katram notikumam Webhooks API atsaucē.

Galvenes

Section titled “Galvenes”
GalveneNozīme
Wink-VersionSavienojuma versija, 2.0.
Wink-Event-IdTāds pats kā id ķermenī — jūsu idempotences atslēga.
Wink-Delivery-IdUnikāls katram galapunktam un notikumam; mainās tikai, ja piegāde tiek atkārtota.
Wink-Event-TypeTāds pats kā type ķermenī.
Wink-Delivery-AttemptŠīs piegādes mēģinājuma numurs, sākot no 1.
Wink-SignatureHMAC paraksts — skatīt zemāk.

Parakstu pārbaude

Section titled “Parakstu pārbaude”

Katram webhook ir parakstīšanas slepenā atslēga (whsec_…), ko Wink parāda vienu reizi, kad izveido webhook vai nomaina tā slepeno atslēgu. Saglabājiet to kā paroli. Katrs piegādes pieprasījums satur

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

kur t ir Unix laika zīmogs (sekundes) un v1 ir mazajiem burtiem hex formātā HMAC-SHA256 no virknes t + "." + rawBody, parakstīts ar jūsu slepeno atslēgu, un rawBody ir precīzs pieprasījuma ķermeņa baitu saturs, kāds tas tika saņemts — nepārrakstiet JSON pirms pārbaudes. 24 stundas pēc slepenās atslēgas nomaiņas galvene satur otro v1= vērtību, kas parakstīta ar iepriekšējo slepeno atslēgu; pieņemiet piegādi, ja kāds no v1 atbilst.

Pārbaudiet četros soļos: parsējiet t un katru v1; pārrēķiniet HMAC pār t.rawBody ar jūsu slepeno atslēgu; salīdziniet ar konstanta laika salīdzinājumu; noraidiet, ja |now − t| pārsniedz jūsu toleranci (ieteicams 5 minūtes).

// Node.js (Express stils; pārliecinieties, ka jums ir RAW ķermenis, nevis parsēts objekts)
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)));
}

Nomainiet slepeno atslēgu portālā vai ar POST /api/managing-entity/{id}/webhook/{webhookId}/rotate-secret; atbilde parāda jauno slepeno atslēgu vienu reizi, un vecā atslēga turpina darboties 24 stundas, kamēr to izplatāt.

Mēģinājumi un atkārtota piegāde

Section titled “Mēģinājumi un atkārtota piegāde”
  • Atbildiet ar jebkuru 2xx 10 sekunžu laikā, lai apstiprinātu saņemšanu. Smago apstrādi veiciet asinhroni.
  • 5xx, laika pārsniegums, 408 vai 429 tiek mēģināti atkārtoti ar aizkavi: pēc 1 minūtes, 5 minūtēm, 30 minūtēm, 2 stundām, 6 stundām, 12 stundām, tad katru dienu — 10 mēģinājumi aptuveni 3 dienu laikā — pēc tam piegāde tiek atzīmēta kā mirusi.
  • Jebkura cita 4xx tiek uzskatīta par “jūs noraidījāt šo piegādi” un netiek mēģināta atkārtoti.
  • Katrs notikums, piegāde un mēģinājums (statuss, atbildes fragments) ir redzams sadaļā Applications > Webhooks un caur API (…/webhook/event/grid, …/webhook/delivery/grid). Jūs varat atkārtoti piegādāt jebkuru piegādi (POST …/webhook/delivery/{deliveryId}/redeliver, kas sāk jaunu mēģinājumu sēriju), atkārtoti piegādāt visas mirušās piegādes vienlaikus (POST …/webhook/{webhookId}/redeliver-dead), vai atcelt vienu.
  • Piegādes tiek glabātas 30 dienas.

Testa notikumi

Section titled “Testa notikumi”

Nosūtiet sev sintētisku webhook.test notikumu no portāla vai ar POST /api/managing-entity/{id}/webhook/{webhookId}/test. Tas ir parakstīts un piegādāts tieši kā īsts notikums, tāpēc varat pārbaudīt savu galapunktu, paraksta pārbaudi un idempotences apstrādi pirms abonējat reālos notikumus.

Labākās prakses

Section titled “Labākās prakses”
  • Izmantojiet HTTPS — Wink nosūta datus tikai uz HTTPS galapunktiem.
  • Atbildiet ātri — Atgrieziet 200 OK tiklīdz saņemat datus. Smago apstrādi veiciet asinhroni.
  • Idempotence — Jūsu apstrādātājam jābūt idempotentam; deduplikācija pēc Wink-Event-Id. Wink mēģina atkārtot, ja nesaņem 2xx atbildi.
  • Avota pārbaude — Pārbaudiet Wink-Signature galveni (skatīt Parakstu pārbaude) pirms apstrādes; noraidiet visu, kas neiztur pārbaudi.
  • Žurnālu veidošana — Žurnālojiet katru saņemto webhook datus. Tas ievērojami atvieglo integrācijas problēmu novēršanu.

Pauzēšana un dzēšana

Section titled “Pauzēšana un dzēšana”

Jūs varat atspējot webhook, to nedzēšot. Tas pauzē piegādi, lai varētu novērst problēmas, nezaudējot konfigurāciju. Kad esat gatavs, ieslēdziet to atpakaļ.

Webhook dzēšana to neatgriezeniski noņem. Jebkura integrācija, kas paļaujas uz šo webhook, pārstās saņemt paziņojumus.

Papildu lasāmviela

Section titled “Papildu lasāmviela”