API : configurer et gérer les webhooks

Les webhooks envoient des événements d’edoobox à une adresse technique de réception de votre intégration. Vous pouvez, par exemple, y recharger une réservation modifiée dans le CRM. La gestion des webhooks s’effectue via la ressource API /v2/webhook. Ce guide s’adresse aux développeurs responsables de l’intégration.

Préparer le rôle, l’accès API et l’adresse de réception

La configuration nécessite un accès API avec droit d’écriture sur les webhooks ; le droit de lecture est aussi nécessaire pour la relecture. Une clé disposant uniquement de droits de lecture ne peut pas créer de configuration de webhook. Le droit Zapier préparé comprend la gestion des webhooks ; le droit WordPress ne permet ici que la lecture. Pour une intégration propre, utilisez un groupe de droits limité de manière appropriée et vérifiez ses autres droits.

Préparez une adresse HTTPS durablement accessible de votre propre serveur, par exemple https://example.org/integrationen/edoobox.
Générez un secret de webhook aléatoire propre et enregistrez-le de manière sûre chez le destinataire. Ce secret est distinct de celui de la clé API.
Créez ou vérifiez l’accès API sous Clés API et droits d’accès.
Authentifiez-vous selon API : premiers pas avec l’hôte, le jeton Bearer et edid appropriés.
Vérifiez les droits de ressources nécessaires et la disponibilité de votre intégration dans le compte. Un accès API autorisé ne décrit pas à lui seul la portée métier d’une connexion quelconque.

La procédure générale de configuration API ne doit pas être confondue avec un webhook de prestataire de paiement ou une adresse de réception de scanner. Ces connexions possèdent leurs propres guides métier et identifiants.

Créer d’abord le webhook inactif

Envoyez POST /v2/webhook avec Content-Type: application/json et vos en-têtes habituels Authorization et edid. Le corps suivant est un exemple ; remplacez l’adresse de réception et le secret par vos propres valeurs.

{
  "data": {
    "status": false,
    "url": "https://example.org/integrationen/edoobox",
    "secret": "EIGENES_ZUFAELLIGES_WEBHOOK_SECRET",
    "topics": ["post_Booking", "put_Booking"]
  }
}

Vérifiez le statut HTTP et error dans la réponse et conservez l’identifiant public de webhook renvoyé. Utilisez le même identifiant pour les modifications ultérieures ; si le résultat est incertain, ne créez pas une seconde entrée sans vérification. Consultez d’abord GET /v2/webhook/list.

Champ	Utilisation
`status`	`false` pour préparer, `true` pour recevoir les événements correspondants.
`url`	Adresse technique de réception de votre serveur.
`secret`	Secret partagé pour la signature HMAC. Conservez-le en sécurité ; ne considérez pas la valeur relue comme une sauvegarde complète.
`topics`	Liste des noms d’événements souhaités.
`basicauth`	Accès HTTP Basic Auth supplémentaire facultatif du destinataire. À utiliser uniquement si sa configuration est adaptée en conséquence.

Les descriptions complètes des champs et les opérations HTTP figurent dans la référence API v2.

Choisir délibérément les topics et les relire

Pour les réservations, post_Booking et put_Booking sont notamment attestés. Ils représentent la création et la modification dans les procédures de réservation correspondantes. Un nom de topic ne doit pas être inventé librement à partir d’un statut métier tel que « payé ». Vérifiez l’événement métier réellement nécessaire avec une réservation de démonstration appropriée.

Relisez la configuration via GET /v2/webhook/{id} et comparez l’URL, le statut et les topics enregistrés. Les entrées inconnues ou mal orthographiées peuvent être ignorées à l’enregistrement ; une réponse réussie ne confirme pas à elle seule que tous les noms souhaités ont été repris.

La mise à jour de la liste topics définit la liste souhaitée complète. Une liste vide retire les topics enregistrés. Envoyez donc aussi les noms d’événements toujours nécessaires.

Vérifier la réception et la signature sur le corps inchangé

edoobox envoie un HTTP POST avec du JSON. L’en-tête edhook identifie l’envoi précis. Si un secret est enregistré, edsignature contient une signature HMAC-SHA256 hexadécimale du corps JSON envoyé. Calculez la comparaison à partir des octets reçus inchangés. Analyser d’abord le JSON et le sérialiser de nouveau peut modifier l’ordre ou le codage des caractères.

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

function validEdooboxSignature(rawBody, signature, secret) {
  if (typeof signature !== 'string' || !/^[0-9a-f]{64}$/i.test(signature)) {
    return false;
  }
  const expected = createHmac('sha256', secret).update(rawBody).digest();
  const received = Buffer.from(signature, 'hex');
  return expected.length === received.length && timingSafeEqual(expected, received);
}
// Conserver rawBody dans un Buffer non modifié avant le passage d’un parseur JSON.
// Lire secret dans le coffre sécurisé du serveur.

Vérifiez d’abord la signature et l’attribution à la connexion configurée. Traitez ensuite le contenu JSON. Celui-ci contient une rubrique hook avec notamment topic, time, method, account et webhook, ainsi qu’une rubrique data. La forme des données dépend de l’événement et de son mode de génération ; une extension peut contenir des données supplémentaires.

La valeur de contexte hook.edid n’est pas un jeton d’accès API. Pour une récupération REST ultérieure, continuez d’utiliser votre propre authentification API réussie et son contexte de compte.

Activer et vérifier le parcours complet

Relisez la configuration préparée et vérifiez le destinataire, la configuration du secret et les topics.
Activez-la avec PUT /v2/webhook/{id} et le corps {"data":{"status":true}}.
Dans un parcours de démonstration convenu, déclenchez une nouvelle réservation ou une modification appropriée.
Chez le destinataire, vérifiez le HTTP POST réel, le topic, la signature, la forme des données et l’identifiant de réservation.
Rechargez la ressource concernée avec votre propre accès API et contrôlez l’actualisation dans le système cible.
Vérifiez aussi le nouveau traitement de la même réservation et un destinataire temporairement indisponible.

L’expéditeur n’attend que brièvement la réponse de réception. Enregistrez donc d’abord durablement un événement vérifié dans votre propre file d’attente et répondez rapidement avec HTTP 200. Votre service en arrière-plan traite ensuite les tâches CRM plus longues. Un accusé de réception ne devrait être envoyé que lorsque votre système peut reprendre de manière fiable le travail accepté.

Gérer les événements multiples et les absences de remise

Utilisez edhook, le topic et l’identifiant de ressource pour un traitement traçable. Empêchez les réservations ou actions CRM en double même si la même modification de ressource arrive par différents canaux. L’état de traitement de votre système cible doit être conservé dans son stockage durable.

Ne prévoyez ni une remise exactement une fois, ni un ordre fixe, ni des intervalles de répétition garantis. Vérifiez le journal réel de réception et comparez l’enregistrement edoobox actuel. Le rapprochement REST des réservations complémentaire traite les annulations ultérieures, la déduplication et l’état de traitement qui n’est finalisé qu’après un parcours complet.

Si les messages n’arrivent pas, vérifiez le statut actif, les topics enregistrés, l’action réellement exécutée, l’adresse de réception, le pare-feu, le contrôle de signature et le journal du destinataire. Un GET API sur une réservation ne génère pas lui-même d’événement de création ou de modification. Ne lancez pas de véritables réservations multiples pour le dépannage.

Modifier l’adresse, le secret ou le fonctionnement de manière contrôlée

Au besoin, désactivez la configuration avec PUT /v2/webhook/{id} et {"data":{"status":false}}. Relisez ensuite le statut. Cette désactivation ne retire pas de la file du destinataire le travail qu’il a déjà accepté.

Modifiez l’URL, le secret et les topics avec le même identifiant. Coordonnez un changement de secret entre la configuration de l’expéditeur et le destinataire et vérifiez la signature avant la réactivation. Si une entrée doit disparaître définitivement, DELETE /v2/webhook/{id} permet sa suppression. Vérifiez auparavant les dépendances et conservez le rapprochement REST comme transition contrôlée.

Exemple : reprendre une modification de réservation dans le CRM

Une organisation exploite son propre destinataire pour les réservations. Après une signature valide, il enregistre le message et confirme la réception. Le service en arrière-plan identifie la réservation concernée, lit son état edoobox actuel et actualise l’association CRM déjà enregistrée. Un nouvel événement de la même réservation actualise le même enregistrement.

Un traitement REST régulier rapproche aussi l’ensemble pertinent de réservations. Une perturbation temporaire de réception reste ainsi gérable. Cet exemple nécessite une intégration propre ; créer un webhook ne crée pas encore un rapprochement CRM complet.