AiVideoEditor
Comece grátis
Menu

Revisado em 2026-11-11 · Versão da API 2026-11-09 · Ler Markdown

Webhooks do cliente

Entrega de eventos de saída para o seu espaço de trabalho. Registre um endpoint HTTPS, verifique o segredo de assinatura de uso único e receba eventos assinados com repetições limitadas.

Registrar um endpoint

curl -s -X POST -H "Authorization: Bearer $PUBLISHER_KEY" \
  -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  $BASE/webhooks -d '{"url": "https://example.com/hooks/autoposted"}'
  • O segredo de assinatura (whsec_…) é retornado uma única vez: na primeira resposta bem-sucedida de criação. Guarde-o; uma repetição idempotente da mesma criação retorna o endpoint sem o segredo, e ele não pode ser exibido novamente.
  • Os destinos devem ser HTTPS, publicamente resolvíveis e estar livres de credenciais embutidas. Requisições para endereços privados, de loopback, link-local (incluindo metadados de nuvem), unique-local e multicast são recusadas antes de qualquer conexão ser feita, e redirecionamentos nunca são seguidos.
  • O registro enfileira um evento webhook.verification direcionado para esse endpoint, independente do filtro eventTypes dele. Os eventos comuns só fluem depois que seu endpoint responde à verificação com 2xx.

Verificando as entregas

Toda requisição carrega:

CabeçalhoSignificado
x-publisher-event-idID de evento estável: idêntico entre repetições e replays
x-publisher-event-typeTipo de evento, por exemplo post.published
x-publisher-timestampSegundos Unix
x-publisher-signaturet=<ts>,v1=<hex>

A assinatura é HMAC-SHA256 sobre ${t}.${event_id}.${raw_body} usando o seu segredo de assinatura. Verifique com uma tolerância de ±300 segundos e rejeite replays fora dela. Exemplo em Node:

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(secret, headers, rawBody) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(headers['x-publisher-signature']);
  if (!m) return false;
  const [t, v1] = [Number(m[1]), m[2]];
  if (Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(`${t}.${headers['x-publisher-event-id']}.${rawBody}`)
    .digest('hex');
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Sempre verifique contra o corpo bruto da requisição antes de interpretá-lo.

Envelope de evento

{
  "id": "0192d0d0-0000-7000-8000-00000000000f",
  "type": "post.published",
  "createdAt": "2026-11-09T12:00:01Z",
  "apiVersion": "2026-11-09",
  "data": { "postId": "…", "deliveryId": "…", "accountId": "…" }
}

Catálogo inicial de eventos (extensível; eventTypes filtra no registro):

  • webhook.verification: payload de desafio; responda 2xx para ativar o endpoint
  • post.published: um destino confirmado com um recibo nativo
  • delivery.failed: um destino falhou de forma terminal
  • delivery.requires_action: consentimento/reconexão/revisão tardia necessários

Os resultados agregados de publicações (post.partially_published, post.failed) ainda não são emitidos; eles são documentados aqui somente quando um produtor existir, então não dependa deles. Assine os eventos por destino acima e derive o estado do lote a partir dos resultados de entrega da publicação.

Repetições, replay e desativação

  • Tentativas: imediatamente, depois +1m, +5m, +30m, +2h, +8h. As repetições reutilizam o mesmo ID de evento e corpo idêntico byte a byte, para que você possa deduplicar com segurança.
  • 2xx = entregue. 429/5xx/timeouts repetem. Outros 4xx falham permanentemente para aquele evento (corrija o endpoint e depois faça o replay).
  • 410 Gone desativa o endpoint: nenhum evento adicional é enfileirado para ele.
  • O replay autorizado pelo operador, por meio do serviço interno de webhooks, reenvia um evento com o seu ID original. Uma tentativa em andamento com lease ativo nunca é interrompida; o replay informa que o evento está ocupado e pode ser repetido em breve.

Notas operacionais

  • Os diagnósticos de entrega armazenam apenas códigos de resultado seguros: nunca o seu segredo, assinaturas, cabeçalhos de requisição ou corpos de resposta. Os payloads são adicionalmente higienizados: segredos de provedor/OAuth e URLs de presign de mídia são removidos antes de qualquer coisa ser enfileirada.
  • Os endpoints têm escopo por espaço de trabalho: possuir um UUID de endpoint de outro espaço de trabalho não tem efeito algum.
  • A entrega é at-least-once por ocorrência de evento aceita; deduplique por x-publisher-event-id.

Disponibilidade das ferramentas do desenvolvedor

A página Developers lista as chaves de API do espaço de trabalho e os endpoints de webhook de forma independente da configuração de criptografia de segredos de assinatura. Criar um webhook exige uma configuração de criptografia de servidor válida; peça ao operador da implantação para resolver um aviso de configuração. O gerenciamento de chaves de API permanece disponível. Os segredos de assinatura existentes nunca são exibidos novamente.