Pourquoi votre callback de tâche hiapi ne se déclenche pas, et comment y remédier

Pourquoi votre callback de tâche hiapi ne se déclenche pas

Vous avez soumis une tâche à POST https://api.hiapi.ai/v1/tasks avec un objet callback ; la tâche est terminée (vous voyez status: "success" lorsque vous faites GET /v1/tasks/{taskId}), mais votre endpoint n'a jamais reçu la notification d'état final. Aucune requête n'a atteint votre serveur. Aucune nouvelle tentative. Rien dans les journaux.

Les callbacks hiapi sont livrés sous forme de POST HTTPS de serveur à serveur, depuis l'extérieur de votre réseau. Si un maillon de cette chaîne pose problème — URL inaccessible depuis l'internet public, TLS impossible à négocier, votre gestionnaire qui ne renvoie pas 2xx assez rapidement, ou votre validation de signature qui rejette la requête de votre côté — alors du point de vue de votre application, cette notification est « silencieuse ». La bonne nouvelle : il s'agit presque toujours de l'une de quelques erreurs de configuration, et chacune est facile à vérifier.

Causes fréquentes (par ordre de probabilité)

1. L'URL de callback n'est pas accessible depuis l'internet public. localhost, 127.0.0.1, une IP interne à votre VPC, ou un tunnel ngrok expiré — hiapi ne peut y accéder.
2. Problème HTTPS / TLS. Certificat auto-signé, certificat expiré, chaîne intermédiaire manquante, ou nom d'hôte non concordant. hiapi n'envoie de POST que vers des URL commençant par https:// et valide la chaîne de certificats.
3. Votre gestionnaire ne renvoie pas 2xx dans le délai imparti. Si vous effectuez des opérations longues de manière synchrone dans votre gestionnaire de callback (écriture en base de données, téléchargement d'images, envoi de notifications), la requête expire avant que vous ne renvoyiez 200. Du point de vue de hiapi, c'est un échec.
4. Vous n'avez jamais enregistré de Webhook Sign Key et votre gestionnaire rejette les requêtes non signées. Si aucune clé de signature n'est générée dans Settings, le corps de requête livré par hiapi ne contient pas d'en-tête de signature — tout middleware de validation que vous avez écrit considérera la requête comme invalide et la rejettera.
5. L'objet callback a été omis lors de la soumission. Il est facultatif. Si vous ne l'avez pas inclus dans votre POST /v1/tasks, rien ne se déclenchera. Vous devez à la place interroger GET /v1/tasks/{taskId}.
6. La tâche est encore en cours. Le callback ne se déclenche qu'à l'état final (success ou fail). Tant que status vaut queued, handling ou archiving, aucun callback n'est envoyé.
7. L'hôte de l'URL de callback figure sur une liste de refus / le pare-feu de votre entreprise bloque le trafic sortant vers celui-ci. Moins courant, mais cela vaut la peine de vérifier si vous êtes dans un environnement périmétrique strict.

Solutions : liste de contrôle en 7 étapes

1. Confirmez que la tâche a bien atteint un état final. curl -H "Authorization: Bearer $HIAPI_KEY" https://api.hiapi.ai/v1/tasks/tk-hiapi-.... Si status vaut queued ou handling, le callback ne s'est pas encore déclenché — attendez, ne déboguez pas.
2. Confirmez que vous avez soumis l'objet callback. Relisez le corps de requête que vous avez envoyé à POST /v1/tasks. Si callback est absent, c'est la réponse — ajoutez-le et soumettez à nouveau, ou passez à l'interrogation.
3. Testez l'URL de callback depuis l'internet public. Depuis n'importe quelle machine extérieure à votre réseau (un téléphone en réseau cellulaire, un shell cloud, un outil curl en ligne), exécutez curl -i -X POST https://your.domain.example/hiapi/callback -d '{}' -H "Content-Type: application/json". Vous devez recevoir une réponse HTTP 2xx de votre propre serveur. Si vous obtenez un refus de connexion, une erreur DNS, ou toute réponse autre que 2xx, corrigez d'abord ce problème.
4. Vérifiez la chaîne de certificats TLS. curl -vI https://your.domain.example/hiapi/callback 2>&1 | grep -i 'ssl\|cert'. Recherchez SSL certificate problem. Si vous voyez cette erreur, installez la chaîne de certificats complète (certificat feuille + intermédiaires), ou utilisez un certificat géré (Let's Encrypt, CDN, ACM).
5. Renvoyez 200 immédiatement, puis traitez de façon asynchrone. Dans votre gestionnaire : écrivez la charge utile dans une file / une table de données, renvoyez 200 OK, puis traitez le travail dans un worker en arrière-plan. Ne laissez pas la réponse être bloquée par des appels en aval lents.
6. Générez le Webhook Sign Key et unifiez votre méthode de validation. Rendez-vous à /en/dashboard/settings → Webhook Sign Key → Generate, puis enregistrez la clé. Si votre gestionnaire valide les signatures, utilisez la clé enregistrée ; sinon, désactivez temporairement la validation, confirmez que la livraison fonctionne, puis réactivez-la.
7. Consultez /en/dashboard/logs. Les journaux d'appels affichent la requête et son état final. Comparer le request_id de vos journaux d'appels avec ce que votre serveur a réellement reçu (le cas échéant) est le moyen le plus rapide de distinguer « le callback a-t-il quitté hiapi » de « le callback a-t-il atteint mon serveur ».

Exemple de vérification minimal

Utilisez ce qui suit pour confirmer de bout en bout votre clé API, le chemin de création de tâche et votre endpoint de callback. Choisissez un modèle d'image rapide pour un test de fumée ; selon la documentation publique, les ID de modèle incluent un suffixe de capacité :

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2/text-to-image",
    "input": {"prompt": "a cute cat"},
    "callback": {"url": "https://your.domain.example/hiapi/callback"}
  }'

Vous devriez recevoir immédiatement une réponse JSON contenant un taskId, de la forme tk-hiapi-.... Ensuite, une fois que la tâche passe à success ou fail, surveillez les journaux de votre serveur pour détecter un POST entrant vers /hiapi/callback. Si l'étape de création de tâche elle-même renvoie 401 Unauthorized, le problème vient de la clé — consultez Pourquoi hiapi renvoie 429 (et que faire) pour comprendre comment fonctionne l'enveloppe d'erreur de hiapi (la même structure hiapi_error s'applique à tous les codes de statut).

Liens associés

• API Keys — vérifiez que votre clé est valide et que ses permissions sont correctes
• Settings — générez ou renouvelez votre Webhook Sign Key
• Call Logs — confirmez que hiapi a envoyé le callback et le statut de la réponse
• API Reference — spécification complète de POST /v1/tasks et GET /v1/tasks/{id}
• Limite de débit 429 de hiapi — détail de l'enveloppe d'erreur pour les problèmes connexes du type « vous recevez un statut mais aucun callback »

FAQ

hiapi réessaie-t-il les callbacks en échec ? Un callback n'est considéré comme livré que si votre endpoint renvoie une réponse 2xx. Si votre gestionnaire renvoie 5xx, expire, ou si la négociation TLS échoue, considérez le callback comme non livré. Le modèle le plus robuste : pour toute tâche soumise avec un callback, interrogez toujours GET /v1/tasks/{taskId} en solution de repli. Ainsi, même une défaillance ponctuelle sur le chemin du callback ne fait pas perdre le résultat.

L'URL de callback peut-elle utiliser HTTP plutôt que HTTPS ? Non. Seules les URL commençant par https:// sont acceptées. Si vous testez en local, utilisez un tunnel qui termine le TLS pour vous (Cloudflare Tunnel, ngrok, tailscale funnel) et pointez le callback vers un endpoint HTTPS public.

Pourquoi mon gestionnaire reçoit-il le corps de la requête, mais la validation de signature échoue-t-elle ? Soit (a) vous avez généré le Webhook Sign Key après avoir soumis la tâche — la requête a été signée avec l'ancienne clé (ou sans clé) — donc régénérez, enregistrez, et soumettez une nouvelle tâche ; soit (b) votre code de validation reconstruit la chaîne canonique différemment de hiapi. Enregistrez les octets exacts du corps reçu par votre serveur, et relancez le HMAC sur ces octets exacts, sans aucune resérialisation JSON intermédiaire.

Le taskId affiche success, mais je n'ai reçu ni callback ni URL de résultat. Refaites GET /v1/tasks/{taskId} pour consulter le tableau output. Les URL dans output[*].url ont une durée limitée (expireAt) ; téléchargez immédiatement. La livraison du callback et la validité de l'URL sont deux problèmes distincts — même sans callback, l'endpoint GET est la source de vérité.

Je vois le callback dans /en/dashboard/logs, mais mon serveur ne l'a jamais enregistré. Cela signifie que le problème se situe dans votre périmètre réseau, pas chez hiapi. Les causes fréquentes incluent : des règles CDN / WAF qui bloquent les requêtes POST sans User-Agent identifiable par votre équipe, une liste d'IP autorisées sur le pare-feu, ou un proxy inverse qui réécrit le chemin. Autorisez ce POST entrant sur le pare-feu, puis réessayez.

L'URL de callback consomme-t-elle la limite de débit de mon compte ? Non. Les callbacks sont des livraisons de hiapi vers vous, indépendantes de votre budget de débit POST /v1/tasks.