Webhook « audio prêt » : être prévenu quand la version audio d'un article existe

Quand un CMS envoie un article à une API de synthèse vocale, l'audio ne sort pas toujours dans la seconde. Un article de 8 000 signes se fabrique vite, un dossier de 60 000 signes prend plus de temps, et pendant ce temps votre site doit savoir quoi afficher. Il existe trois façons d'attendre : bloquer la publication, interroger le serveur en boucle, ou demander à être prévenu. Ce dernier geste s'appelle un webhook, et c'est celui qui tient le mieux quand le volume monte.

Cet article décrit ce que fait le nôtre, tel qu'il est écrit dans le code, y compris ses limites.

Les trois façons d'attendre un audio

Attendre dans la réponse. L'appel de génération accepte un paramètre wait. Avec wait à vrai, la réponse ne revient qu'une fois la synthèse terminée et contient directement l'adresse du fichier : l'article se publie déjà sonorisé. C'est le plus simple, mais ce n'est valable que jusqu'à 20 000 caractères ; au-delà, le paramètre est sans effet et l'appel répond tout de suite.

Interroger l'état. Sans wait, l'API répond par un 202 avec l'identifiant de l'article et du travail. Vous pouvez ensuite demander l'état de l'article jusqu'à ce qu'il soit prêt. Ça marche, mais un intégrateur finit toujours par choisir un intervalle trop court (charge inutile) ou trop long (audio en retard sur l'article).

Être prévenu. Vous passez une adresse webhook_url dans l'appel de génération. Quand l'audio est prêt, nous appelons cette adresse avec le résultat. Votre CMS n'a rien à surveiller : il réagit.

Si vous découvrez l'API, commencez par l'appel minimal et sa réponse ; le webhook vient se greffer dessus sans rien changer au reste.

Ce que contient l'appel

Le webhook est une requête POST en JSON envoyée à votre adresse. Le corps porte :

• article_id : notre identifiant de l'article ;
• external_id : le vôtre, si vous l'avez fourni à l'envoi, ce qui permet de retrouver l'article chez vous sans table de correspondance ;
• status : l'état de l'audio ;
• audio_url : l'adresse du fichier, quand il peut circuler ;
• duration_s, version et voice : la durée en secondes, le numéro de version et la voix utilisée.

Le champ status prend trois valeurs, et c'est là que le webhook est plus utile qu'il n'y paraît :

• ready : l'audio est en ligne, audio_url est rempli ;
• pending_review : votre compte demande une validation humaine avant diffusion. L'audio existe mais attend quelqu'un ; audio_url est alors vide et un champ review_url mène à l'espace client. C'est le pendant automatique de la relecture avant publication ;
• scheduled : l'article a une date de publication future. L'audio est prêt mais ne doit pas encore être servi ; le corps porte publish_at et toujours pas d'adresse de fichier.

Le principe est le même dans les deux derniers cas : un audio qui n'est pas censé être écouté ne circule pas, même vers votre propre serveur.

Lorsqu'un article corrigé est relu seulement sur les phrases qui ont changé, le corps porte en plus partial: true, avec le nouveau numéro de version.

Vérifier que l'appel vient bien de nous

Une adresse de webhook est une porte ouverte sur votre CMS : n'importe qui peut y envoyer un faux « audio prêt ». Chaque appel est donc signé. Trois en-têtes l'accompagnent :

• X-WeDispatch-Timestamp : l'horodatage de l'envoi, en secondes ;
• X-WeDispatch-Signature : sha256= suivi d'un HMAC-SHA256 calculé sur la chaîne « horodatage, point, corps brut » avec votre secret de signature ;
• X-WeDispatch-Delivery : l'identifiant unique de cette livraison.

De votre côté, la vérification tient en quatre lignes : recalculer le HMAC sur le corps tel que reçu (avant toute conversion JSON), comparer en temps constant, rejeter un horodatage trop ancien pour qu'un appel intercepté ne puisse pas être rejoué des heures plus tard. C'est le même schéma que celui des grands services de paiement, ce qui veut dire que la plupart des frameworks ont déjà une fonction pour le faire.

Le secret de signature est propre à votre compte et s'affiche dans l'espace client, sur la page des sites, au propriétaire du compte et à ses administrateurs seulement. Un rédacteur qui branche un webhook doit le leur demander.

Ce qui se passe quand votre serveur ne répond pas

Votre serveur peut être en maintenance au moment exact où l'audio sort. La règle est la suivante :

• en cas d'erreur réseau, de délai dépassé, de réponse 5xx ou de 429, nous retentons, jusqu'à trois essais au total, avec une courte pause croissante entre deux ;
• une réponse 2xx arrête là, évidemment ;
• un autre 4xx (une adresse introuvable, un refus) arrête aussi : un 404 ne deviendra pas un 200 en insistant ;
• chaque essai attend dix secondes au plus, et les redirections ne sont pas suivies.

Tous les essais d'une même livraison portent le même X-WeDispatch-Delivery. Si votre serveur a bien traité un appel mais que sa réponse s'est perdue en route, le suivant arrivera avec le même identifiant : gardez la trace des identifiants reçus et ignorez un doublon.

Au bout de trois échecs, le webhook n'est pas rejoué plus tard. L'audio, lui, est bien là : l'état de l'article reste consultable par l'API, et c'est le bon filet de sécurité pour un CMS qui veut rattraper ce qu'il a manqué.

Ce que le webhook ne fait pas

Mieux vaut le savoir avant d'écrire le code d'intégration :

• il n'y a pas de webhook au niveau du compte. L'adresse se passe à chaque appel de génération et n'est jamais retenue. Si vous cherchez l'écran où la configurer une fois pour toutes, il n'existe pas, et notre documentation publique le dit au même endroit ;
• l'adresse doit être en https et publique. Une adresse locale, une IP privée ou un nom qui se résout vers le réseau interne sont refusés dès l'appel (400), puis vérifiés de nouveau au moment de l'envoi ;
• il ne signale pas un échec de fabrication. Si un audio ne peut pas être produit, le compte est prévenu par courriel, pas par le webhook ;
• les alertes de quota (seuil d'avertissement, quota atteint) partent vers la même adresse quand elle est fournie, mais en un seul essai : la prochaine alerte suivra de toute façon.

Faut-il un webhook pour votre site ?

Si vous êtes sur WordPress, non : le module gère cette attente pour vous, et la page WordPress décrit ce qu'il fait. Le webhook sert à ceux qui branchent eux-mêmes un CMS maison, headless ou un outil d'automatisation, comme dans notre guide d'intégration par API. Pour eux, c'est la différence entre une intégration qui interroge le serveur sans fin et une intégration qui ne fait rien tant qu'il n'y a rien à faire.

À lire aussi

• Faire lire une fiche produit à voix haute : prix, tailles, avis et références
• Écrire les nombres en chiffres ou en lettres : ce que ça change à l'écoute
• Ajouter l'audio à son site sans développeur : ce qui est vraiment sans code