Guide d’implémentation
Une tâche média survit à l’appel HTTP qui l’a créée, à la page qui l’a déclenchée et souvent au déploiement en cours à ce moment-là. Tout ce qui suit sert à y survivre.
L’enjeu
Entre l’envoi et le fichier en main, il y a quatre endroits où perdre du travail : une création réexpédiée à l’aveugle après un délai dépassé, un rappel invérifiable, une boucle d’interrogation qui matraque ou abandonne, et une URL de résultat expirée pendant votre réflexion.
01
Idempotency-Key fait qu’une répétition du même modèle, de la même entrée et du même rappel sous 24 heures renvoie la tâche d’origine sans réserver deux fois. La portée est une clé d’API ; une clé voisine rejouant la même valeur reçoit 409 sans identifiant de tâche.
02
Les livraisons portent X-Webhook-Timestamp et une HMAC-SHA256 en Base64 dans X-Webhook-Signature, calculée sur taskId.timestamp.sha256(raw_body). Vérifiez sur les octets bruts en temps constant et rejetez les horodatages anciens avant de toucher à l’état de la tâche ou de la facturation.
03
recordInfo est un secours, pas un transport. Commencez vers deux secondes, augmentez de moitié, plafonnez à quinze et arrêtez-vous à une échéance que vous avez choisie.
La méthode
Persistez la clé d’idempotence, le taskId et votre propre identifiant de corrélation dans la transaction qui répond à l’appelant. Chaque événement ultérieur — rappel, interrogation, reprise, question de support — se résout sur cette ligne, et une livraison en double devient une mise à jour et non une seconde commande.
Vérifier d’abord, lire ensuite. La signature couvre les octets bruts : on analyse après la comparaison.
Verify the callback before you trust it
import { createHash, createHmac, timingSafeEqual } from "node:crypto";
// rawBody is the exact bytes that arrived. Parse only to read the task ID:
// the digest is always computed over those raw bytes, never over a re-encode.
export function verifyDelivery(rawBody, headers, webhookKey) {
const timestamp = headers["x-webhook-timestamp"];
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const taskId = JSON.parse(rawBody).data.taskId; // payload version 2
const digest = createHash("sha256").update(rawBody).digest("hex");
const expected = createHmac("sha256", webhookKey)
.update(`${taskId}.${timestamp}.${digest}`)
.digest("base64");
const sent = Buffer.from(headers["x-webhook-signature"] ?? "", "utf8");
const mine = Buffer.from(expected, "utf8");
return sent.length === mine.length && timingSafeEqual(sent, mine);
}Delivery headers
X-Webhook-Timestamp: 1788652800
X-Webhook-Signature: <base64>
X-Webhook-Payload-Version: 2
{
"code": 200,
"msg": "success",
"request_id": "whd_01k3m8x9q2z4v7n5p6r8s0t1w3",
"data": { "taskId": "job_01k3…", "state": "succeeded", "settled": true, … }
}Contrat
| Champ ou en-tête | Valeur ou limite |
|---|---|
| Idempotency-Key | 24 h · scoped to one API key |
| X-Webhook-Signature | base64(HMAC-SHA256) |
| signed string | taskId.timestamp.sha256(raw_body) |
| X-Webhook-Payload-Version | 2 for new integrations |
Balayez horizontalement pour voir toutes les colonnes.
Intégration
Pertinence
Vérifications
L’enveloppe est {code, msg, data, request_id} sur toutes les opérations /api/v1. En version 2 de charge utile, le request_id d’une livraison reste stable entre les renvois : c’est la clé de déduplication naturelle.
cost avec settled: false est l’estimation réservée ; settled: true est la facturation finale. Un succès ne dépasse jamais la réservation, un échec ou une expiration la libère intégralement.
errorCode vaut l’une de neuf valeurs stables : invalid_request, unsupported_combination, content_rejected, rate_limited, upstream_unavailable, generation_failed, timeout, invalid_asset, upstream_failed. Traitez toute autre valeur comme upstream_failed.
Avant la mise en production
Questions fréquentes
Modèles
Chaque lien ouvre la page de la famille de modèles concernée : entrées, limites, politique de contenu et prix actuel à l’unité.
Et après
Envoyer de longues tâches média depuis votre serveur et les terminer sûrement : clés d’idempotence, rappels signés, interrogation bornée, cinq états.
