Se você não usa WordPress, mas um CMS próprio, uma loja virtual ou uma automação como Make ou n8n, o calendário de SEO envia os posts aprovados por webhook direto para o seu sistema. O FlowSEO envia o texto pronto em JSON para um endereço escolhido por você e assina cada mensagem, para que você possa verificar que ela veio de nós. Este guia é para quem vai configurar o recebimento.
Criar o webhook
- Abra o Calendário de SEO e clique em Gerenciar automações.
- Em Publicação, clique em Conectar WordPress ou webhook.
- Em Tipo de conexão, escolha Webhook.
- Se quiser, informe um Nome (opcional) e preencha em Endereço do webhook o endereço do seu receptor. Só https é permitido, e o FlowSEO não segue redirecionamentos.
- Opcional: abra Cabeçalho próprio (opcional) e informe um cabeçalho que o FlowSEO envia em cada mensagem, por exemplo
Authorizationcom o valorBearer <seu token>ouX-Api-Key. Mais na seção “Cabeçalho próprio” abaixo. - Clique em Salvar e verificar.
Em seguida, o FlowSEO mostra uma única vez o Segredo do webhook. Copie com Copiar e guarde no seu sistema, pois ele só aparece agora. A nova conexão passa a estar disponível em Publicação. Clique em Salvar para o calendário usá-la.
Ao salvar, o FlowSEO envia uma mensagem de teste do tipo ping, que em data traz apenas domain.host. Se o seu receptor não responder com um status 2xx, aparece “Conexão salva, a verificação falhou:” com o motivo.
No mesmo diálogo, Como é a mensagem mostra os cabeçalhos, um exemplo completo com o seu domínio, a verificação da assinatura em PHP e Node.js e como o FlowSEO avalia a sua resposta. O exemplo é gerado pelo mesmo código com que o FlowSEO envia.
O que o FlowSEO envia
Cada mensagem é um POST com conteúdo JSON. Na data programada chega um evento do tipo content.published. De forma resumida, fica assim:
{
"id": "6f1c2a9e-5b7d-4c3e-9a10-2f8e4d6b1c55",
"type": "content.published",
"created_at": "2026-11-12T09:41:00+01:00",
"data": {
"domain": { "uuid": "…", "host": "exemplo.com.br" },
"publish_at": "2026-11-12T09:41:00+01:00",
"previous": null,
"content": {
"uuid": "…",
"type": "guide",
"language": "pt",
"main_keyword": "mesa de jantar para espaços pequenos",
"title": "Mesa de jantar para espaços pequenos: 7 ideias",
"slug": "mesa-de-jantar-para-espacos-pequenos",
"meta_title": "…",
"meta_description": "…",
"og_title": "…",
"og_description": "…",
"planned_url": "https://exemplo.com.br/guias/mesa-de-jantar-para-espacos-pequenos",
"version": 3,
"html": "<p>…</p>",
"markdown": "…",
"json_ld": [
{ "@context": "https://schema.org", "@type": "BlogPosting", "headline": "…" }
],
"images": [
{ "role": "hero", "url": "https://…", "alt": "…", "title": "…", "caption": "…", "section_key": null }
]
}
}
}
Pontos importantes para a implementação:
htmlemarkdowntrazem o texto sem o título. O título vem emtitle.imagestraz as imagens prontas, com função, texto alternativo e legenda, a imagem principal primeiro.json_ldé uma lista de objetos schema.org que você pode incluir sem alterações num<script type="application/ld+json">.previousvem preenchido em uma atualização, comexternal_ideurlda publicação anterior. Assim você sobrescreve um post existente em vez de criar um novo.
Verificar a assinatura
Cada mensagem traz três cabeçalhos no padrão “Standard Webhooks”:
webhook-id: o ID único da mensagem, igual aoidno JSON.webhook-timestamp: o momento do envio, em segundos desde 1970.webhook-signature: a assinatura no formatov1,<Base64>.
A assinatura é um HMAC-SHA256 sobre {webhook-id}.{webhook-timestamp}.{corpo bruto}. A chave é o segredo do webhook exatamente como o FlowSEO exibiu, em texto. As bibliotecas prontas de Standard Webhooks, porém, esperam um segredo com o prefixo whsec_ e por isso não servem diretamente; as poucas linhas abaixo bastam. Em PHP, a verificação fica assim:
$base = $id.'.'.$timestamp.'.'.$rawBody;
$expected = 'v1,'.base64_encode(hash_hmac('sha256', $base, $secret, true));
$valid = hash_equals($expected, $signatureHeader);
Em Node.js:
const crypto = require('node:crypto');
const expected = 'v1,' + crypto.createHmac('sha256', secret)
.update(`${id}.${timestamp}.${rawBody}`)
.digest('base64');
const valid = signatureHeader.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
Use sempre o corpo bruto da requisição, sem alterações, e não um JSON gerado de novo. Verifique também se o timestamp não é antigo demais, com no máximo cinco minutos, por exemplo, e processe cada webhook-id uma única vez: cada repetição da mesma entrega traz o mesmo webhook-id. Assim não surge post duplicado quando a sua resposta não chegou ao FlowSEO.
Cabeçalho próprio
Se o seu receptor espera uma credencial própria, como um token, você guarda exatamente um cabeçalho com nome e valor. O FlowSEO o envia em cada mensagem, inclusive no ping.
- O nome só pode ter letras, dígitos e os caracteres
! # $ % & ' * + - . ^ _ ` | ~, sem espaços.Authorizationé permitido. Os cabeçalhos que o próprio FlowSEO define (webhook-id,webhook-timestamp,webhook-signature,Content-Type,Content-Length,Host,User-Agente cabeçalhos de conexão comoConnectionouTransfer-Encoding) não podem ser sobrescritos. - O valor é uma linha sem quebras. Ele é guardado criptografado e nunca mais exibido; o diálogo mostra apenas Definido. Se você deixar o campo vazio ao editar, o valor guardado continua valendo enquanto o endereço do webhook for o mesmo. Se você alterar o endereço, informe o valor de novo, para que ele nunca vá a outro receptor sem você perceber.
- Remover cabeçalho apaga o cabeçalho, assim como esvaziar o nome e salvar.
- O cabeçalho não faz parte da assinatura. Verifique-o também se o usa como proteção de acesso, e confie na assinatura para saber a origem da mensagem.
Retornar o endereço publicado
Se o seu sistema responder com status 2xx e um JSON como {"url": "https://exemplo.com.br/guias/mesa-de-jantar-para-espacos-pequenos", "id": "4711"}, o FlowSEO registra esse endereço como endereço publicado. Em vez de url, o campo também pode se chamar link. Qualquer outra resposta de sucesso conta como entregue, só que sem endereço. Um endereço fora do seu domínio não é aceito.
Se algo não funcionar
Ao salvar uma conexão, o FlowSEO informa o motivo:
- “O outro lado recusou a solicitação.” O seu receptor respondeu com um status de erro, muitas vezes por falha na verificação da assinatura. Verifique se está usando o corpo bruto e o segredo correto.
- “O endereço redireciona. Informe o endereço final.” Informe o endereço em que a requisição realmente chega.
- “O endereço não é acessível publicamente ou não usa https.” O receptor precisa estar acessível pela internet via https.
- “A conexão excedeu o tempo limite.” O FlowSEO espera no máximo 60 segundos. Responda de imediato e processe o post depois, em segundo plano.
Redirecionamentos (3xx) e respostas com 401, 403, 404, 410 ou outro status 4xx encerram a entrega na hora. Em caso de tempo limite excedido, erros de conexão, status 408 e 429 e erros de servidor (5xx), o FlowSEO tenta entregar de novo, até três vezes no total, após um e após cinco minutos. Se falhar de vez, aparece no calendário “A publicação falhou:” seguido do motivo. Como programar de novo está em A publicação no WordPress não funciona.
Perdeu o segredo? Um novo segredo para uma conexão existente é gerado pela nossa equipe, e o antigo deixa de valer na hora. Como alternativa, crie uma nova conexão de webhook e selecione-a no calendário.