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.verificationdirecionado para esse endpoint, independente do filtroeventTypesdele. Os eventos comuns só fluem depois que seu endpoint responde à verificação com 2xx.
Verificando as entregas
Toda requisição carrega:
| Cabeçalho | Significado |
|---|---|
x-publisher-event-id | ID de evento estável: idêntico entre repetições e replays |
x-publisher-event-type | Tipo de evento, por exemplo post.published |
x-publisher-timestamp | Segundos Unix |
x-publisher-signature | t=<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 endpointpost.published: um destino confirmado com um recibo nativodelivery.failed: um destino falhou de forma terminaldelivery.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.