Guia de implementação
Uma tarefa de mídia sobrevive à chamada HTTP que a criou, à página que a disparou e muitas vezes ao deploy que estava rodando na hora. Tudo aqui serve para aguentar isso.
O desafio
Entre apertar enviar e ter o arquivo existem quatro lugares para perder trabalho: uma criação reenviada às cegas depois do tempo esgotado, um retorno que você não consegue verificar, um laço de consulta que martela ou desiste, e uma URL de resultado que expirou enquanto você decidia o que fazer.
01
Idempotency-Key faz com que repetir o mesmo modelo, entrada e retorno em até 24 horas devolva a tarefa original sem reservar de novo. O escopo é uma chave de API; uma chave irmã repetindo o mesmo valor recebe 409 e nenhum identificador de tarefa.
02
As entregas trazem X-Webhook-Timestamp e um HMAC-SHA256 em Base64 no X-Webhook-Signature, calculado sobre taskId.timestamp.sha256(raw_body). Verifique contra os bytes crus em tempo constante e recuse carimbos antigos antes de mexer no estado da tarefa ou da cobrança.
03
recordInfo é reserva, não transporte. Comece perto de dois segundos, cresça metade a cada vez, limite em quinze e pare num prazo escolhido por você.
A abordagem
Persista a chave de idempotência, o taskId e o seu identificador de correlação na mesma transação em que responde a quem chamou. Todo evento seguinte — retorno, consulta, repetição, dúvida de suporte — resolve contra aquela linha, e uma entrega duplicada vira uma atualização em vez de um segundo pedido.
Verifique primeiro, leia depois. A assinatura cobre os bytes crus, então a análise vem depois da comparação.
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, … }
}Contrato
| Campo ou cabeçalho | Valor 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 |
Deslize horizontalmente para ver todas as colunas.
Integração
Adequação
Evidências
O envelope é {code, msg, data, request_id} em todas as operações /api/v1. Na versão 2 de payload, o request_id da entrega é estável entre reenvios, então serve naturalmente como chave de deduplicação.
cost com settled: false é a estimativa reservada; settled: true é a cobrança final. O sucesso nunca ultrapassa a reserva, e falha ou expiração libera tudo.
errorCode é um de nove valores estáveis: invalid_request, unsupported_combination, content_rejected, rate_limited, upstream_unavailable, generation_failed, timeout, invalid_asset, upstream_failed. Qualquer outro valor deve ser tratado como upstream_failed.
Antes de lançar
Perguntas frequentes
Modelos
Cada link abre a página daquela família de modelos: entradas, limites, política de conteúdo e o preço atual por unidade.
A seguir
Envie trabalhos longos do seu servidor e conclua com garantia: chaves de idempotência, retornos assinados, consulta limitada e cinco estados.
