Utiliser les webhooks

Les workflows Fullwhere peuvent déclencher un webhook vers votre système. Chaque exécution envoie une requête POST vers l’URL configuré. Pour en savoir plus sur la mise en place d'un webhook via les workflows Fullwhere, consulter notre article dédié. //LINK TODO

À savoir

Les appels Webhook seront toujours des requêtes POST.

Fullwhere considère l’appel comme réussi uniquement si votre endpoint renvoie un code 2xx (200-299).

Interprétation des webhooks

En-têtes envoyés

Les Headers suivant seront toujours présents dans la requête :

• Content-Type: application/json
• User-Agent: Fullwhere-Workflow-Webhook
• X-Fullwhere-Webhook-Timestamp: <timestamp>
• X-Fullwhere-Webhook-Signature: sha256=<signature>

Vous pouvez aussi configurer // LINK TODO des en-têtes personnalisés. Ils sont fusionnés avec les en-têtes système. Si un header personnalisé utilise le même nom qu'un header Fullwhere, la valeur renvoyée sera celle du header Fullwhere.

Corps de la requête

{
  "event": "workflow.action.webhook",
  "workflow": {
    "id": "workflow_id",
    "name": "Nom du workflow"
  },
  "action": {
    "id": "action_id",
    "key": "action_key",
    "description": "Description de l'action"
  },
  "feedback": {
    "id": "feedback_content_id",
    "contextId": "feedback_id"
  },
  "metadata": {
    "key": "value"
  }
}

Chaque champ correspond à la structure suivante :

• event : valeur fixe workflow.action.webhook
• workflow.id : uuid du workflow
• workflow.name : nom du workflow
• action.id : uuid de l’action du workflow
• action.key : clé unique de l’action
• action.description : description de l’action
• feedback.id : uuid de feedback associé
• feedback.contextId : uuid du contexte associé
• metadata : paires clé-valeur définies dans la configuration du webhook

Vérifier les webhooks

Recommandations

Vérifier un webhook est une étape de sécurité essentielle. Sans vérification, un tiers peut envoyer une requête vers votre endpoint en imitant Fullwhere. Dans ce cas, votre application peut traiter un événement falsifié comme s’il était légitime. Cela peut déclencher des actions métier non voulues ou exposer une faille exploitable.

Pour éviter cela, chaque webhook est signé à l'aide d'une clé unique. Cette signature permet ensuite de vérifier que le webhook provient bien de Fullwhere, et de ne le traiter que si tel est le cas.

Une autre faille de sécurité potentielle réside dans ce que l’on appelle les « attaques par rejeu ». Une attaque par rejeu se produit lorsqu’un attaquant intercepte une charge utile valide (y compris la signature) et la retransmet à votre terminal. Cette charge utile passera la validation de la signature et sera donc traitée. Pour atténuer ce risque, un timestamp (en-tête Fullwhere-Webhook-Timestamp) est inclus dans chaque requête, indiquant l’heure à laquelle la tentative de webhook a eu lieu. Nous vous recommandons de rejeter les webhooks dont le timestamp s’écarte de plus de cinq minutes (en avant ou en arrière) par rapport à l’heure actuelle.

Éléments de signatures

Chaque appel de webhook comprend donc deux en-têtes contenant des informations supplémentaires utilisées à des fins de vérification :

• X-Fullwhere-Webhook-Timestamp: <timestamp> : timestamp en seconde
• X-Fullwhere-Webhook-Signature: sha256=<signature> : la signature encodée en Base64

Construction de la chaîne signée

La chaîne signée correspondant au timestamp et au payload, séparés par le caractère . :

<timestamp>.<rawBody>

timestamp correspondant au timestamp de l'envoi du webhook, présent dans le header X-Fullwhere-Webhook-Timestamp et rawBody est le JSON sérialisé de la requête.

L’en-tête reçu a donc cette forme :

X-Fullwhere-Webhook-Signature: sha256=<hex>

Déterminer la signature attendue

Chaque webhook est signé avec l’algorithme HMAC SHA-256. Le secret utilisé est celui du compte Fullwhere.

Pour calculer la signature attendue, vous devez donc appliquer l'algorithme HMAC à la chaîne signée en utilisant le secret de votre compte Fullwhere.

Cette signature générée doit correspondre à l'une de celles envoyées dans l'en-tête X-Fullwhere-Webhook-Signature.

Exemple de code (NodeJS)

const crypto = require('crypto');
function verifyFullwhereWebhookSignature({
  rawBody,
  timestamp,
  signature,
  webhookHmacSecret,
}) {
  const expectedSignature = crypto
    .createHmac('sha256', webhookHmacSecret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  const receivedSignature = signature.replace(/^sha256=/, '');

  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature, 'hex'),
    Buffer.from(receivedSignature, 'hex'),
  );
}

Générer le secret de votre compte Fullwhere

Pour vérifier les webhooks, vous aurez donc besoin de générer votre secret HMAC.

Pour cela, en tant que membre Administrateur de votre compte Fullwhere, accédez à la section Paramètres, puis Développeurs, et dans l'onglet Webhooks, générez ou re-générez votre secret HMAC.