Envoyer les soumissions vers un webhook et réessayer ce que votre récepteur a manqué

Un webhook envoie chaque soumission acceptée vers une URL qui vous appartient, en quelques secondes : un contact peut ainsi arriver dans votre CRM ou dans votre propre code sans attendre un résumé par e-mail. Les webhooks font partie de FormFlow depuis la v1.0.0. Ce tutoriel ajoute un point de terminaison, montre ce que reçoit votre récepteur et comment le vérifier, puis aborde ce qui compte le jour où votre récepteur est hors service : ce que FormFlow réessaie tout seul et comment renvoyer le reste avec Réessayer les livraisons échouées.

Ce dont vous avez besoin

Un récepteur que vous contrôlez et qui accepte un POST avec un corps JSON. Son adresse doit être en https et ne doit se résoudre qu’en adresses publiques. Le panneau refuse tout le reste à l’enregistrement : une adresse localhost ne fonctionne donc pas, et un tunnel est la façon habituelle de tester.

Ajouter le point de terminaison

1. Ouvrez le formulaire dans le panneau et allez dans l’onglet Livraison.

2. Sous Points de terminaison du webhook, appuyez sur Ajouter un point de terminaison.

3. Laissez Envoyer comme sur FormFlow JSON (signé). L’autre choix, Message Slack, prend l’URL d’un webhook entrant Slack.

4. Collez l’adresse de votre récepteur dans URL du point de terminaison et laissez Livrer activé.

5. Enregistrez le formulaire. Une notification intitulée Copiez vos secrets de signature de webhook maintenant affiche l’URL et le secret de chaque nouveau point de terminaison. Elle reste à l’écran jusqu’à ce que vous la fermiez, et indique que les secrets ne sont plus affichés ensuite. Conservez le secret dans votre gestionnaire de secrets. Pour en obtenir un nouveau, supprimez le point de terminaison et ajoutez-le de nouveau.

6. Appuyez sur Envoyer le test sur la ligne du point de terminaison. Vous obtenez Test livré, ou La livraison du test a échoué avec le texte d’erreur de votre propre récepteur. La ligne doit d’abord être enregistrée, et le bouton est limité à 20 livraisons de test par heure.

Envoyez ensuite une vraie soumission et ouvrez-la dans le panneau. Son tableau Demandes de livraison liste chaque destination à laquelle cette soumission est due, avec un statut En attente, Loué, Livré ou Mort, le nombre de tentatives, le Numéro de livraison et la dernière erreur.

Ce que reçoit votre récepteur

Un POST par soumission qui n’est pas du spam. Le corps est un petit document JSON, accompagné de trois en-têtes. Voici sa forme, avec des valeurs d’exemple :

{
  "id": "SUBMISSION_UUID",
  "form": { "id": "FORM_UUID", "name": "Contact Us" },
  "submitted_at": "2026-10-08T09:00:00+00:00",
  "data": { "name": "Ada Lovelace", "email": "ada@example.com" }
}

• X-FormFlow-Timestamp est l’heure de la tentative, en secondes.

• X-FormFlow-Signature-256 est sha256= suivi d’un HMAC-SHA256 de l’horodatage, d’un point et du corps brut, avec le secret du point de terminaison comme clé.

• X-FormFlow-Delivery-Id identifie la livraison. Il reste identique à chaque nouvelle tentative.

Vérifiez la signature avant de faire confiance à une requête, sur le corps brut et non sur une copie réencodée. Une version PHP, sous la forme que donne la documentation de l’API de FormFlow :

function formflow_verify(string $rawBody, string $timestamp, string $signature, string $secret): bool
{
    if (abs(time() - (int) $timestamp) > 300) {
        return false;
    }

    $expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);

    return hash_equals($expected, $signature);
}

Ce que FormFlow réessaie tout seul

FormFlow attend jusqu’à 10 secondes une réponse. Toute réponse 2xx compte comme livrée. Un délai dépassé, une connexion coupée, un 408, un 429 ou une réponse 5xx est réessayé, jusqu’à six tentatives au total, avec des attentes de 10 secondes, 1 minute, 5 minutes, 30 minutes et 2 heures entre elles. Toute autre réponse, y compris un 3xx ou un 4xx, est traitée comme un refus définitif et n’est pas réessayée automatiquement. FormFlow ne suit pas les redirections : un point de terminaison qui répond par une redirection compte donc comme échoué. Faites pointer le point de terminaison vers son adresse finale.

Si un point de terminaison continue de demander à être réessayé et n’a plus de tentatives, FormFlow désactive Livrer pour lui et prévient par e-mail les propriétaires de l’équipe. Une livraison à court de tentatives s’affiche comme Mort. Le tableau de bord continue aussi de lister un webhook dont le transfert est désactivé, avec sa série d’échecs, jusqu’à ce qu’une livraison réussisse.

Réessayer ce que votre récepteur a manqué

Avant la v1.33, chaque soumission manquée demandait son propre Réessayez maintenant. Désormais, un seul appui couvre un point de terminaison. La version figure dans le journal des modifications. L’ordre compte :

1. Réparez d’abord le récepteur. Chaque livraison échouée obtient un essai de plus : une nouvelle tentative contre un récepteur encore en panne ne fait qu’échouer de nouveau.

2. Dans l’onglet Livraison, vérifiez l’interrupteur Livrer du point de terminaison. Si FormFlow l’a désactivé, activez-le et enregistrez le formulaire. Réessayer un point de terminaison désactivé est refusé avec « Activez Livrer et enregistrez le formulaire, puis réessayez. »

3. Appuyez sur Réessayer les livraisons échouées sur la ligne du point de terminaison et confirmez. La boîte de dialogue indique que chaque livraison échouée qui peut encore être envoyée est remise en file d’attente, avec son ID de livraison et sa charge utile d’origine.

4. Une notification vous indique combien ont été mises en file d’attente. Un appui en met au plus 500. S’il en reste, elle vous demande d’appuyer de nouveau.

5. Ouvrez une soumission et consultez son tableau Demandes de livraison. Le nombre de tentatives a augmenté et le statut devrait atteindre Livré.

Si vous changez l’URL, le secret ou le format d’un point de terminaison, il repart de zéro. Les livraisons effectuées avant le changement ne sont pas renvoyées, et depuis la v1.35.1 le tableau de bord ne compte plus les anciens échecs contre la nouvelle adresse. Désactiver puis réactiver un point de terminaison sans le modifier conserve son historique d’échecs.

Limites à connaître

• Un nouveau point de terminaison ne reçoit que les soumissions qui arrivent après sa configuration. On ne lui envoie pas celles que vous avez déjà.

• Le spam n’est pas transféré.

• Réessayer les livraisons échouées ne renvoie que les livraisons qui peuvent encore être envoyées, et seulement vers le point de terminaison tel qu’il est maintenant.

• La livraison se fait au moins une fois. Votre récepteur doit tolérer une répétition.