Ontwikkelaars · voor Ontwikkelaars

Webhooks

Ontvang ondertekende realtime events (boekingen, inchecken, betalingen, ontgrendelde verblijven, extra's, berichten) en controleer de HMAC-SHA256-signatuur.

Webhooks sturen events naar je systeem op het moment dat ze plaatsvinden, zodat je de API niet hoeft te pollen.

Events #

Wat data bevat #

De machineleesbare versie van elk event (headers, body en data) staat in de sectie webhooks van het OpenAPI-document en in de API-referentie.

Een webhook toevoegen #

Settings → Webhooks: vul een https://-URL in, vink de gewenste events aan (geen = alle) en klik op Add webhook. Het signing secret (ondertekeningsgeheim) wordt één keer getoond: bewaar het bij je ontvanger.

Het verzoek #

POST met een JSON-body:

{
  "id": "evt_…",
  "event": "payment.completed",
  "createdAt": "2026-11-18T14:03:11.000Z",
  "tenant": "t_…",
  "data": { "bookingId": "b_…", "leg": "eco", "status": "paid" }
}

Headers:

De handtekening controleren (Node.js) #

const crypto = require('crypto');
function verify(rawBody, headers, secret) {
  const ts = headers['x-gp-timestamp'];
  const expected = 'v1=' + crypto.createHmac('sha256', secret).update(ts + '.' + rawBody).digest('hex');
  const given = String(headers['x-gp-signature'] || '');
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  return fresh && given.length === expected.length && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}

Controleer altijd tegen de ruwe request-body en weiger oude timestamps om replay-aanvallen te blokkeren.

De handtekening controleren (C# / .NET) #

using System.Security.Cryptography; using System.Text;
static bool Verify(string rawBody, string ts, string signature, string secret) {
  if (!long.TryParse(ts, out var t) || Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - t) > 300) return false;
  using var h = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
  var hex = Convert.ToHexString(h.ComputeHash(Encoding.UTF8.GetBytes(ts + "." + rawBody))).ToLowerInvariant();
  return CryptographicOperations.FixedTimeEquals(Encoding.ASCII.GetBytes("v1=" + hex), Encoding.ASCII.GetBytes(signature ?? ""));
}

Gebruik op .NET Framework BitConverter.ToString(hash).Replace("-", "").ToLowerInvariant() in plaats van Convert.ToHexString, en vergelijk in constante tijd met een eenvoudige lus.

De handtekening controleren (PHP) #

$expected = 'v1=' . hash_hmac('sha256', $_SERVER['HTTP_X_GP_TIMESTAMP'] . '.' . file_get_contents('php://input'), $secret);
$ok = abs(time() - (int)$_SERVER['HTTP_X_GP_TIMESTAMP']) < 300 && hash_equals($expected, $_SERVER['HTTP_X_GP_SIGNATURE'] ?? '');

Bezorging en nieuwe pogingen #

Antwoord binnen 10 seconden met een willekeurige 2xx-status. Mislukte bezorgingen worden na 30 seconden en na 5 minuten opnieuw geprobeerd (in totaal drie pogingen). Recent deliveries toont de laatste 200 pogingen met hun resultaat.

• id in de body en de header X-GP-Delivery blijven bij elke nieuwe poging gelijk: sla ze op en negeer duplicaten.
• Events kunnen in een andere volgorde aankomen; gebruik createdAt en haal de boeking op voor de actuele status.
• Redirects worden niet gevolgd en alleen openbare https://-adressen worden aangeroepen (geen privé- of lokale netwerken).
• Verzoeken worden verstuurd met Content-Type: application/json en User-Agent: GuestPortal-Webhooks/1.

Veelgestelde vragen #

Krijg ik de volledige boeking in het event? #

Het event bevat ID's en de wijziging. Haal de volledige boeking op met GET /api/v1/bookings/{id} met een API-sleutel; zo gaan er geen persoonsgegevens mee in webhook-bodies.

Kunnen kanalen webhooks naar Guestbud sturen? #

Ja, dat is de andere richting. Hostaway en Channex kunnen Guestbud direct informeren over nieuwe en gewijzigde reserveringen; zie Hostaway en Channex. Die inkomende adressen zijn geheim per bedrijf en starten alleen een nieuwe import van die reservering.

Worden er webhooks verstuurd vanuit het demoaccount? #

Nee.