Stökkva að meginefni
Wink

Vefkrokar Samþætting

Vefkrokar leyfa kerfum þínum að fá rauntímatilkynningar þegar atvik eiga sér stað á Wink reikningnum þínum — nýjar bókanir, afbókanir, uppfærslur á greiðslum og fleira. Þessi leiðarvísir leiðir þig í gegnum uppsetningu og bestu vinnubrögð.

Áhorfendur

Kafli sem heitir „Áhorfendur“

Þessi leiðarvísir er fyrir forritara sem eru að samþætta Wink við ytri kerfi eins og eignastýringarkerfi (PMS), rásastjóra, CRM kerfi eða sérsniðin mælaborð.

Hvernig vefkrokar virka

Kafli sem heitir „Hvernig vefkrokar virka“
  1. Þú skráir vefkroka slóð á Wink.
  2. Þegar atvik á sér stað (t.d. ný bókun) sendir Wink HTTP POST til slóðarinnar þinnar.
  3. Þinn netþjónn vinnur úr gögnum og svarar með 200 OK.

Uppsetning vefkroka

Kafli sem heitir „Uppsetning vefkroka“
  1. Skráðu þig inn á reikninginn þinn (Extranet, Studio eða TripPay — allir styðja vefkroka).
  2. Farðu í Applications og síðan Webhooks. Sjá Webhooks.
  3. Smelltu á Create webhook.
  4. Sláðu inn nafn (t.d. “PMS Booking Sync”).
  5. Sláðu inn vefkroka slóðina þína — HTTPS endapunkt á netþjóninum þínum.
  6. Veldu atvik — Veldu tiltekna atburði til að gerast áskrifandi að, eða skildu tómt til að fá öll atvik.
  7. Kveiktu á Enabled.
  8. Smelltu á Save — svar sýnir þér undirritunarlykilinn einu sinni; geymdu hann núna.

Tegundir atvika

Kafli sem heitir „Tegundir atvika“

Wink birtir í dag 70 tegundir af vefkroka atvikum yfir bókanir, eignir, reikninga (stjórnunaraðilar) og birgðir (herbergistegundir, verðáætlanir, aðalverð, aukahlutir, aðstaða, sölurásir, kynningar). Algeng dæmi:

FlokkurDæmi
Bókunbooking.create, booking.cancelled, booking.refund.partial, booking.refund.full, booking.review.created
Eignproperty.created, property.status.updated, property.policy.updated
Birgðirroom_type.updated, rate_plan.created, master_rate.updated, special_rate.created, sales_channel.created
Reikningurmanaging_entity.created, managing_entity.status.updated, managing_entity.manager.added

Heildarlistinn — með lýsingu, hver fær það og tengil á hverja atburðasíðu — er Webhook Events Catalog. Tilvísunarsíða fyrir hvert atvik (JSON líkami, hausar, endurtekningarstefna) er að finna í Webhooks API.

Skoða allar tegundir atvika

Hvað þú færð

Kafli sem heitir „Hvað þú færð“

Hver sending er HTTP POST til vefkroka slóðarinnar þinnar með Content-Type: application/json og þessari umbúð:

{
  "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": { "...": "event-specific payload, e.g. BookingWebhookPayload" }
}
  • id — auðkenni atviksins; eins fyrir alla endapunkta reikningsins sem fá þetta atvik og fyrir allar endurtilraunir. Notaðu það sem þinn idempotency lykil.
  • type — lykill atviksins (sendur einnig sem Wink-Event-Type haus). Greindu á type og schemaVersion til að vinna úr object.
  • object — valin samantekt á auðlindinni sem atvikið snýst um (auðkenni, staða, þau svæði sem þú vinnur með) auk links.self, canonical REST slóð birgjahliðsins á fullri auðlind. Sækja með þínum eigin API auðkennum þegar þú þarft meira en samantektina; ef þú færð atvikið sem endursöluaðili eða ferðaskrifstofa, notaðu samsvarandi auðlindarendapunkt á þínu eigin API yfirborði fyrir sama auðkenni.

Hver gagnaskema er skjalfest fyrir hvert atvik í Webhooks API tilvísuninni.

Hausar

Kafli sem heitir „Hausar“
HausMerking
Wink-VersionÞráðsamningsútgáfa, 2.0.
Wink-Event-IdEins og id í líkamanum — þinn idempotency lykill.
Wink-Delivery-IdEinstakt fyrir hvern endapunkt fyrir hvert atvik; breytist aðeins ef þú sendir aftur.
Wink-Event-TypeEins og type í líkamanum.
Wink-Delivery-AttemptTilraunarnúmer, byrjar á 1, fyrir þessa sendingu.
Wink-SignatureHMAC undirskrift — sjá hér að neðan.

Staðfesting undirskrifta

Kafli sem heitir „Staðfesting undirskrifta“

Hver vefkroki hefur undirritunarlykil (whsec_…) sem Wink sýnir einungis einu sinni, þegar þú býrð til vefkrokann eða snýrð lykli hans. Geymdu hann eins og lykilorð. Hver sending ber með sér

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

þar sem t er Unix tímastimpill (sekúndur) og v1 er lágstafaður hex HMAC-SHA256 af strengnum t + "." + rawBody, undirritaður með þínum lykli, og rawBody er nákvæm beiðnalíkamsbitar eins og þeir komu — ekki endurraða JSON áður en staðfesting fer fram. Í 24 klukkustundir eftir lykilskipti ber hausinn með sér annar v1= gildið undirritað með fyrri lykli; samþykktu sendinguna ef eitthvert v1 passar.

Staðfestu í fjórum skrefum: greindu t og öll v1; reiknaðu HMAC yfir t.rawBody með þínum lykli; berðu saman með tímasamkvæmni; hafnaðu ef |now − t| fer yfir þol (mælt er með 5 mínútum).

// Node.js (Express-stíll; vertu viss um að hafa RAW líkama, ekki greindan hlut)
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)));
}

Snúðu lykli við úr vefsvæðinu eða með POST /api/managing-entity/{id}/webhook/{webhookId}/rotate-secret; svarið sýnir nýja lykilinn einu sinni, og sá gamli heldur áfram að staðfesta í 24 klukkustundir meðan þú dreifir honum.

Endurtilraunir og endursendingar

Kafli sem heitir „Endurtilraunir og endursendingar“
  • Svaraðu með hvaða 2xx innan 10 sekúndna til að staðfesta móttöku. Gerðu þung vinnsla í bakgrunni.
  • 5xx, tímamörk, 408 eða 429 eru endurtilraunað með vaxandi bið: eftir 1 mínútu, 5 mínútur, 30 mínútur, 2 klukkustundir, 6 klukkustundir, 12 klukkustundir, svo daglega — 10 tilraunir yfir um 3 daga — eftir það er sendingin merkt sem dauð.
  • Önnur 4xx eru talin sem “þú hafðir hafnað þessari sendingu” og eru ekki endurtilraunað.
  • Hvert atvik, sending og tilraun (staða, svarbrot) er sýnilegt undir Applications > Webhooks og í gegnum API (…/webhook/event/grid, …/webhook/delivery/grid). Þú getur endur sent hvaða sendingu sem er (POST …/webhook/delivery/{deliveryId}/redeliver, sem byrjar nýja tilraunarröð), endur sent allar dauðar sendingar vefkroka í einu (POST …/webhook/{webhookId}/redeliver-dead), eða hætt við eina.
  • Sendingar eru varðveittar í 30 daga.

Prufuatvik

Kafli sem heitir „Prufuatvik“

Sendu þér gervi webhook.test atvik úr vefsvæðinu eða með POST /api/managing-entity/{id}/webhook/{webhookId}/test. Það er undirritað og sent nákvæmlega eins og raunverulegt atvik, svo þú getur staðfest endapunktinn þinn, undirritunarskoðun og meðhöndlun idempotency áður en þú gerist áskrifandi að lifandi atvikum.

Bestu vinnubrögð

Kafli sem heitir „Bestu vinnubrögð“
  • Notaðu HTTPS — Wink sendir gögn aðeins til HTTPS endapunkta.
  • Svaraðu hratt — Skilaðu 200 OK um leið og þú færð gögnin. Gerðu þunga vinnslu í bakgrunni.
  • Idempotency — Meðhöndlarinn þinn ætti að vera idempotent; fjarlægðu tvítekningu með Wink-Event-Id. Wink reynir aftur ef það fær ekki 2xx svar.
  • Staðfestu uppruna — Staðfestu Wink-Signature hausinn (sjá Staðfesting undirskrifta) áður en þú vinnur úr; hafnaðu öllu sem mistekst.
  • Skráning — Skráðu hvert vefkroka gagn sem þú færð. Þetta auðveldar bilanaleit verulega.

Stöðvun og eyðing

Kafli sem heitir „Stöðvun og eyðing“

Þú getur slökkt á vefkroka án þess að eyða honum. Þetta stöðvar sendingar svo þú getir leyst úr vandamálum án þess að tapa stillingum. Þegar þú ert tilbúinn, kveiktu aftur á honum.

Eyðing vefkroka fjarlægir hann varanlega. Öll samþætting sem byggir á þeim mun hætta að fá tilkynningar.

Frekari lesning

Kafli sem heitir „Frekari lesning“