Recevoir nos réservations

Quand un voyageur réserve sur Localoge, nous vous prévenons. Bloquez alors ces nuits chez vous, sans quoi vous continuerez à les proposer ailleurs.

Déclarer votre URL

curl -X PUT https://localoge.com/api/v1/channel/webhooks \
  -H "Authorization: Bearer $LOCALOGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://partenaire.example.com/webhooks/localoge" }'

{ "success": true, "data": { "id": "…", "url": "…", "secret": "whsec_9f2c…", "events": [] } }

HTTPS obligatoire. Une liste events vide veut dire tous les événements ; précisez-la pour n’en recevoir qu’une partie.

Ou depuis votre espace, sans écrire une ligne

Dans votre espace développeur, ouvrez votre application, renseignez l’URL de webhook et enregistrez : le secret s’affiche, une seule fois, au même endroit. C’est le même mécanisme, la même signature, le même comportement. À utiliser si vous voulez recevoir vos premiers événements avant d’avoir écrit votre client d’API.

L’écran vous dit si la livraison est réellement branchée, et non seulement si une adresse est enregistrée. Un bouton y régénère le secret : l’ancien meurt à la seconde où le nouveau s’affiche, déployez-le chez vous immédiatement.

Les événements

Événement	Quand
`reservation.created`	Un voyageur a réservé sur Localoge.
`reservation.cancelled`	Une réservation Localoge est annulée : les nuits sont libres.
`reservation.updated`	Une réservation a changé.
`availability.updated`	L’hôte a modifié ses disponibilités sur Localoge.
`property.updated`	Une annonce a changé.

Nous ne vous renvoyons jamais les réservations que vous nous avez envoyées : vous les connaissez, et vous les rejoueriez chez vous.

Le corps

{
  "event": "reservation.created",
  "event_key": "reservation.created:LOC-3f8a",
  "created_at": "2026-08-26T14:03:11.000Z",
  "data": {
    "reservation_id": "LOC-3f8a…",
    "external_property_id": "PROP-4821",
    "check_in": "2026-09-10",
    "check_out": "2026-09-15",
    "status": "confirmed",
    "guests": 3,
    "total": 72500,
    "currency": "EUR"
  }
}

Aucune donnée personnelle du voyageur ne vous est transmise : ni nom, ni adresse, ni téléphone. Vous avez besoin de savoir que des nuits sont prises, pas qui dort dans le lit.

Vérifier la signature

L’en-tête X-Localoge-Signature porte t=<horodatage>,v1=<hmac>. Le HMAC-SHA256 est calculé sur <horodatage>.<corps brut>, avec votre secret.

import { createHmac, timingSafeEqual } from 'node:crypto';

function signatureValide(secret, corpsBrut, entete, toleranceSec = 300) {
  const m = /^t=(\d+),v1=([0-9a-f]+)$/.exec(entete.trim());
  if (!m) return false;
  const t = Number(m[1]);
  // L'horodatage entre dans le calcul : sans cette fenêtre, un envoi capté
  // resterait rejouable indéfiniment.
  if (Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const attendu = createHmac('sha256', secret).update(`${t}.${corpsBrut}`).digest('hex');
  const a = Buffer.from(attendu, 'hex');
  const b = Buffer.from(m[2], 'hex');
  return a.length === b.length && timingSafeEqual(a, b);
}

Répondez vite, traitez après

Répondez 2xx dès réception, puis traitez en tâche de fond. Nous coupons à 10 secondes.

Toute réponse hors 2xx, et toute absence de réponse, est un échec que nous réessayons.

Réessais

À 1 minute, 5, 15, 1 heure, 6 heures, puis 24 heures. Sept tentatives sur environ 30 heures, après quoi nous abandonnons et un humain est prévenu chez nous.

Déduplication

Un réessai porte le même event_key. Utilisez-le comme clé d’unicité de votre côté : c’est ce qui vous évite de traiter deux fois la même réservation quand notre première tentative a abouti chez vous mais que sa réponse s’est perdue.

L’en-tête X-Localoge-Event-Key porte la même valeur, si vous préférez ne pas lire le corps.

Rattraper ce que vous avez manqué

curl "https://localoge.com/api/v1/channel/reservations?updated_since=2026-08-25T00:00:00Z" \
  -H "Authorization: Bearer $LOCALOGE_KEY"

À appeler après une panne de votre côté, ou une fois par jour par sécurité. Les webhooks sont le chemin rapide, celui-ci est le filet.