FlowSEO

Webhook para o calendário de SEO: receber posts no seu sistema e verificar a assinatura

Publicado em 09. novembro 2026

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

  1. Abra o Calendário de SEO e clique em Gerenciar automações.
  2. Em Publicação, clique em Conectar WordPress ou webhook.
  3. Em Tipo de conexão, escolha Webhook.
  4. 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.
  5. Opcional: abra Cabeçalho próprio (opcional) e informe um cabeçalho que o FlowSEO envia em cada mensagem, por exemplo Authorization com o valor Bearer <seu token> ou X-Api-Key. Mais na seção “Cabeçalho próprio” abaixo.
  6. 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:

  • html e markdown trazem o texto sem o título. O título vem em title.
  • images traz 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">.
  • previous vem preenchido em uma atualização, com external_id e url da 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 ao id no JSON.
  • webhook-timestamp: o momento do envio, em segundos desde 1970.
  • webhook-signature: a assinatura no formato v1,<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-Agent e cabeçalhos de conexão como Connection ou Transfer-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.

Este artigo foi útil?

Voltar para Conteúdo e calendário de SEO