Como usar webhooks no Postoria
Os webhooks do Postoria enviam os resultados de tentativas de publicação concluídas para um endpoint HTTPS público que você controla. Use-os para atualizar um sistema interno de acompanhamento, registrar links de posts publicados no seu CMS ou iniciar um fluxo de trabalho quando uma tentativa de publicação terminar.
Os webhooks estão disponíveis em todos os planos, incluindo o Free. Eles funcionam para posts criados no aplicativo do Postoria e por meio de integrações.
Antes de começar
- Você pode configurar uma URL de webhook por perfil. Ela recebe os eventos selecionados de todos os espaços de trabalho dos quais você é proprietário, incluindo aqueles que você não está visualizando no momento.
- Espaços de trabalho nos quais você é apenas membro da equipe não são incluídos. O proprietário deles gerencia as configurações de webhook desses espaços.
- Seu receptor deve aceitar solicitações HTTP
POSTem uma URL HTTPS acessível publicamente. - A URL pode conter até 2.048 caracteres e não deve incluir nome de usuário, senha ou um fragmento de URL, como
#section. O Postoria não segue redirecionamentos, então informe a URL de destino final. - Você não precisa de uma chave da API pública para receber webhooks. O uso da API pública, do servidor MCP ou da integração do Postoria com n8n continua exigindo o plano Pro ou Agency.
Configure seu webhook
- Abra Configurações, encontre Webhooks e clique em Configurar.
- Informe o endereço do seu receptor em URL do webhook.
- Ligue a opção Ativar webhooks.
- Em Eventos a receber, selecione Publicação concluída com sucesso, Falha na publicação ou ambos. Pelo menos um evento deve estar selecionado enquanto os webhooks estiverem ativados.
- Clique em Salvar. A janela é fechada, e a seção Webhooks mostra Ativado e a URL salva.
- Na seção Webhooks, encontre Segredo de assinatura. O valor fica oculto por padrão. Use o botão de exibir ou copiar para obter o segredo e configurar a verificação de assinatura no seu receptor.
Mantenha o segredo de assinatura privado. Ele permite que seu receptor verifique se uma solicitação foi assinada pelo Postoria para o seu perfil.
Quando o receptor estiver pronto, publique um post e confira o Histórico de webhooks para confirmar que o evento chegou até ele. Ativar os webhooks não envia eventos de posts cuja publicação já havia terminado.
Escolha os eventos de que você precisa
Um evento descreve a tentativa de publicação concluída de um post. O Postoria aguarda a conclusão das publicações selecionadas antes de informar o resultado geral.
| Evento | Configuração | Significado |
|---|---|---|
post.succeeded | Publicação concluída com sucesso | Todas as publicações selecionadas foram concluídas com sucesso. |
post.failed | Falha na publicação | A publicação terminou com uma falha, incluindo casos em que algumas publicações foram bem-sucedidas e outras falharam. |
Por exemplo, se um post for publicado com sucesso em uma conta e falhar em outra, o evento será post.failed. Confira os resultados individuais antes de decidir o que tentar novamente; a publicação bem-sucedida já está no ar.
Esses eventos abrangem tentativas de publicação concluídas. Eles não informam se a mídia está pronta, nem trazem atualizações de análises ou atividades da caixa de entrada. Uma solicitação de agendamento rejeitada ou um erro que impeça o início da publicação não gera um webhook de resultado de publicação. Mantenha uma verificação separada para posts que nunca chegam a um resultado final de publicação.
Leia o corpo da mensagem
O Postoria envia JSON com Content-Type: application/json; charset=utf-8. Este exemplo mostra um post com um resultado bem-sucedido e outro com falha:
{
"id": "evt_7c7b19fd634441f3a0b460f2dc7e6812",
"type": "post.failed",
"occurred_at": "2026-11-15T12:00:00Z",
"workspace_id": 42,
"data": {
"post_id": 1234,
"results": [
{
"account_id": 101,
"link_to_post": "https://example.com/published-post",
"error": null
},
{
"account_id": 102,
"link_to_post": null,
"error": "The social account needs to be reconnected."
}
]
}
}
Os IDs, o link e o erro acima são ilustrativos.
ididentifica o evento e permanece igual em todas as tentativas de entrega.typeépost.succeededoupost.failed.occurred_até o horário UTC em que o Postoria registrou o resultado final da publicação, e não o horário da tentativa de entrega mais recente.workspace_ididentifica o espaço de trabalho. Use-o para encaminhar eventos se seu receptor atender a vários espaços de trabalho.data.post_idé o ID do post no Postoria.data.resultscontém os resultados das publicações com o ID de uma conta social, um link do post publicado quando disponível e um erro quando houver. Tantolink_to_postquantoerrorpodem sernull.
Os resultados usam os mesmos campos dos resultados de posts da API pública. Uma conta pode aparecer mais de uma vez, por exemplo, quando um post contém vários Stories. Não presuma que haverá exatamente um resultado por conta.
Verifique a assinatura
Cada solicitação inclui três cabeçalhos:
| Cabeçalho | Valor |
|---|---|
webhook-id | O ID do evento, correspondente ao campo id no corpo da mensagem. |
webhook-timestamp | O horário Unix em segundos desta tentativa de entrega. |
webhook-signature | v1, seguido de uma assinatura HMAC-SHA256 codificada em Base64. |
Para verificar uma solicitação:
-
Leia o corpo bruto da solicitação antes de interpretar o JSON. Interpretá-lo e serializá-lo novamente pode alterar os bytes e invalidar a assinatura.
-
Remova o prefixo
whsec_do segredo de assinatura e decodifique o valor restante de Base64 para obter a chave de assinatura. -
Una o cabeçalho
webhook-id, o cabeçalhowebhook-timestampe o corpo bruto, nessa ordem, com um ponto literal entre cada parte:webhook-id.webhook-timestamp.raw-request-body -
Calcule o HMAC-SHA256 dos bytes UTF-8 dessa string usando a chave de assinatura decodificada e, em seguida, codifique o resultado em Base64.
-
Compare seu resultado com o valor após
v1,emwebhook-signature, usando uma comparação em tempo constante. -
Verifique se o timestamp assinado está dentro da tolerância de tempo permitida pelo seu receptor para limitar a reutilização de solicitações antigas. Use o timestamp do cabeçalho para essa verificação, pois novas tentativas podem chegar muito depois de
occurred_at.
Rejeite solicitações com cabeçalhos de assinatura ausentes ou inválidos antes de agir com base no conteúdo delas. Use webhook-id para reconhecer eventos que seu receptor já processou.
Responda rapidamente e gerencie novas tentativas
Retorne uma resposta HTTP 2xx em até 10 segundos para confirmar uma entrega. Uma implementação prática verifica a solicitação, armazena o evento e seu ID de forma durável e, então, retorna a resposta. O trabalho posterior mais demorado pode ser executado separadamente após essa confirmação.
O Postoria coloca a entrega inicial na fila assim que o resultado da publicação é registrado. Respostas fora da faixa 2xx, tempos limite excedidos e falhas de conexão acionam novas tentativas automáticas. Respostas de redirecionamento também contam como tentativas de entrega com falha.
As novas tentativas são programadas para 5, 15 e 30 minutos, depois 1, 3, 6, 12 e 24 horas após a primeira tentativa. Esses intervalos são contados a partir da primeira tentativa, e não da tentativa anterior. A entrega pode ocorrer mais tarde se houver atrasos no processamento. A programação prevê até nove tentativas, incluindo a inicial.
O ID do evento e o corpo JSON permanecem iguais em todas as novas tentativas. Cada tentativa recebe um novo timestamp de envio e uma assinatura calculada para aquela tentativa. Entregas duplicadas são possíveis, então garanta que processar o mesmo evento novamente seja seguro. Não conte com a chegada de eventos diferentes na ordem das publicações.
Uma nova tentativa de webhook apenas repete a entrega do resultado. Ela não publica o post novamente.
Consulte o histórico de entregas
Abra Configurações → Webhooks → Histórico de webhooks ou acesse diretamente o Histórico de webhooks.
O histórico abrange os espaços de trabalho dos quais você é proprietário e é mantido por 30 dias. Cada linha mostra o evento, o ID do post, o ID do espaço de trabalho, o status da entrega, o número de tentativas e o último status HTTP. Expanda uma linha para ver o ID da mensagem, os horários das tentativas, o horário da entrega, o erro, se houver, e o corpo JSON.
| Status da entrega | Significado |
|---|---|
| Aguardando | A mensagem está aguardando a entrega inicial ou uma nova tentativa. |
| Enviando | Uma tentativa de entrega está em andamento. |
| Entregue | Seu receptor retornou uma resposta HTTP de sucesso. |
| Falhou | As tentativas de entrega terminaram sem uma resposta HTTP de sucesso. |
O status da entrega e o resultado da publicação são diferentes. Um evento post.failed pode ter o status Entregue: a publicação teve uma falha, mas seu receptor recebeu essa informação com sucesso.
Recarregue a página para ver os status de entrega mais recentes e use Carregar mais para ver mensagens mais antigas. Se o carregamento falhar, Tentar novamente tenta carregar o histórico outra vez. Essas ações não reenviam webhooks.
Altere a URL ou desative os webhooks
Em Configurações → Webhooks, clique em Configurar, atualize a URL ou desligue a opção Ativar webhooks e clique em Salvar. A alteração afeta os novos eventos criados.
Fechar a janela de configuração sem clicar em Salvar descarta suas alterações.
Quando os webhooks estão desativados, a seção Webhooks mostra Desativado e oculta a URL salva e o segredo de assinatura. Clique em Configurar para editar a URL ou ativar os webhooks novamente.
Os eventos já registrados mantêm a URL de destino original e podem continuar com novas tentativas de entrega. Desativar os webhooks não cancela essas entregas pendentes, e alterar a URL não as redireciona para o novo endereço.
Solução de problemas
- Não consigo salvar as configurações: verifique se a URL usa HTTPS, é pública, não contém credenciais incorporadas nem fragmento e respeita o limite de caracteres. Selecione pelo menos um evento ao ativar os webhooks.
- Nenhum evento aparece: verifique se os webhooks estavam ativados antes do término da publicação, se o evento correspondente estava selecionado e se você é proprietário do espaço de trabalho. Um erro antes do início da publicação não faz parte desses eventos.
- A entrega continua falhando: confira o último status HTTP e o erro no Histórico de webhooks. Verifique se o endpoint pode ser acessado diretamente, tem um certificado HTTPS válido, aceita
POSTe retorna2xxem até 10 segundos. - A verificação da assinatura falha: use o corpo bruto, decodifique o segredo de Base64 após remover
whsec_e inclua os valores exatos dos cabeçalhos e os pontos de separação na string assinada. - O mesmo evento chega novamente: elimine duplicatas pelo ID do evento, e não pelo ID do post. Uma tentativa de publicação posterior do mesmo post pode produzir um evento diferente.