Skip to main content

​
Quando escolher a publicação por webhook?

O webhook liga o SORANK a um site personalizado ou a uma automatização capaz de receber um artigo e publicá-lo. É a opção indicada quando já dispõe desse sistema de publicação ou quando a sua equipa pode implementá-lo. O funcionamento compreende três etapas: o SORANK prepara o artigo, transmite-o à sua integração e, em seguida, a sua integração publica-o no seu site. Uma vez configurado este percurso, pode enviar os artigos a partir do SORANK ou utilizar o calendário para automatizar a sua geração e envio. Com o contrato de atualização descrito nesta página, pode também enviar uma nova versão para o artigo existente. Por exemplo, uma modificação preparada no editor é enviada para o seu site quando clica em Enviar a atualização do artigo. Se pretender que o SORANK gira também o alojamento do blog, escolha antes o blog alojado. Se o seu CMS dispõe de um conector nativo, utilize o percurso apresentado em publicar e exportar.

​
Atualizar um webhook existente

Após a atualização do seu servidor, o SORANK deteta automaticamente o suporte a atualizações na próxima publicação ou reenvio, caso a sua integração ainda seja reconhecida como legacy. O SORANK envia webhook.test; uma falha na deteção não impede a entrega habitual. Para acionar a deteção imediatamente, sem desligar o seu webhook:
  1. Abra as definições da integração webhook no SORANK.
  2. Mantenha o mesmo URL e o mesmo secret.
  3. Clique em Guardar.
O seu servidor deve responder a webhook.test com um estado HTTP 2xx e este JSON na raiz:
Esta declaração ativa a atualização dos artigos publicados. Apenas article_url não prova que o seu servidor aceita article.updated. A deteção não recupera retroativamente os URLs em falta: cada publicação concluída deve devolver o seu próprio article_url de acordo com o contrato abaixo. Não tem uma integração SORANK nativa para o seu CMS? O conector Webhook permite-lhe enviar os seus artigos gerados para qualquer URL, Zapier, Make, n8n ou um endpoint personalizado no seu próprio site desenvolvido, para que possa publicar o seu conteúdo onde precisar.

​
Como funciona

Quando publica um artigo no SORANK, enviamos um pedido POST com uma carga útil JSON estruturada para o URL que configurou. O seu endpoint ou ferramenta de automatização pode então processar a carga útil e criar a publicação no seu blog, no seu site personalizado ou em qualquer outra ferramenta que aceite pedidos HTTP recebidos.

​
⚠️ Importante: o webhook envia apenas os dados, é você quem os publica

Este é o ponto mais importante a compreender sobre o conector Webhook. Da nossa parte, o SORANK agrupa tudo o que precisa no JSON (título, slug, corpo HTML completo, meta-descrição, imagens, idioma e muito mais) e envia-o para o seu URL. Assim que este JSON é enviado com sucesso, o SORANK marca a entrega como bem-sucedida. Este estado de “sucesso” confirma uma única coisa: os dados saíram do SORANK e o seu endpoint os aceitou. Um simples aviso de receção histórico não confirma a publicação. Com o contrato versão 2 abaixo, uma resposta concluída com article_url confirma imediatamente a publicação no SORANK; o seu código continua a ser responsável pela publicação efetiva no seu CMS. Ou seja, o webhook é apenas um mecanismo de entrega de dados. Recebê-lo, analisá-lo e publicá-lo no seu CMS é da sua inteira responsabilidade. Se o artigo não aparecer apesar de uma entrega bem-sucedida, verifique a receção, o processamento, a publicação e a resposta devolvida. O estado de entrega por si só não permite identificar a causa.

​
Etapa 1: abrir a integração Webhook

  1. No menu lateral, abra Definições e depois Plataformas de publicação.
  2. Desça até ao cartão Webhook e clique em Conectar o seu site.
Webhooks: Etapa 1: abrir a integração Webhook

​
Etapa 2: configurar o seu endpoint

  1. Cole o seu URL de destino no campo Webhook URL (por exemplo, um catch hook do Zapier, um webhook do Make ou o endpoint do seu próprio servidor).
  2. Se desejar, adicione um Secret token caso o seu endpoint necessite de autenticação. O SORANK irá incluí-lo como token Bearer no cabeçalho Authorization para que o seu servidor possa verificar que a chamada provém do SORANK.
  3. Clique em Test para enviar uma carga útil de exemplo (tipo de evento webhook.test) e confirmar que o seu endpoint responde corretamente.
  4. Clique em Save webhook para ativar a integração.
Webhooks: Etapa 2: configurar o seu endpoint

​
Detalhes do pedido HTTP

Cada webhook que o SORANK envia para o seu endpoint segue o mesmo contrato HTTP. Eis o que o seu servidor irá receber:
  • Method: POST
  • Content-Type: application/json
  • User-Agent: SORANK-Webhook/1.0
  • Authorization: Bearer {webhook_secret} (opcional, enviado apenas se tiver configurado um secret nas definições da sua integração)
Utilize o cabeçalho User-Agent para identificar o tráfego do SORANK nos seus registos, e verifique o cabeçalho Authorization do seu lado para garantir que o pedido provém do SORANK e não de um chamador desconhecido.

​
Estrutura da carga útil do webhook

O SORANK utiliza três eventos com o mesmo envelope (event, delivery_id, timestamp, article). Uma única rota POST HTTPS (por exemplo /sorank-webhook) é suficiente: processe cada valor de event nessa rota e verifique o token Authorization se tiver configurado um secret.

​
Versão 2: publicar, atualizar e devolver o URL

Para ativar a atualização, a sua rota deve responder a webhook.test sem criar conteúdo, com um HTTP 200 e este JSON:
Para article.published, crie o artigo e guarde a associação entre article.id e o seu identificador no seu CMS. Se esta associação já existir, não crie um duplicado. Para article.updated, localize essa associação e substitua o conteúdo do artigo existente. Se o artigo não for encontrado, devolva um erro, por exemplo HTTP 404: uma atualização nunca deve criar um novo artigo. Após uma publicação efetivamente concluída, devolva HTTP 200 ou 201 com:
Após uma atualização concluída, utilize "status": "updated" e o URL público atual. Apenas article_url é pedido, não o URL do sitemap. Forneça um URL HTTPS absoluto no site associado ao perfil SORANK, não o da sua automatização. A resposta deve ser um objeto JSON com menos de 16 KiB; o URL não deve ultrapassar 2 048 caracteres.
Devolva em article_url o URL canónico HTTPS exato do artigo publicado, idêntico à sua tag <link rel="canonical">. Respeite a presença ou ausência de www e da barra final. Por exemplo, se o URL canónico for https://example.com/blog/meu-artigo, devolva-o sem www. Se for https://www.example.com/blog/meu-artigo/, mantenha tanto www como a barra final. O Sorank usa este URL para acompanhar a indexação no Google Search Console. Não devolva um URL alternativo apenas porque redireciona para o artigo ou apresenta o mesmo conteúdo.
Uma resposta versão 2 com status: published ou status: updated e um article_url válido regista imediatamente o URL e apresenta Publicado com a sua ligação, mesmo sem troca de backlinks. O URL deve pertencer ao site do perfil. Estas respostas concluídas não aguardam o verificador periódico. Apenas os recibos accepted ou HTTP 202 ficam pendentes de verificação. Os backlinks são verificados separadamente: confirmar a publicação não prova a presença das ligações nem valida os seus créditos. Se uma atualização falhar, o último URL verificado é conservado. Editar o texto no editor não o envia automaticamente: clique em Enviar a atualização.

​
Novas tentativas e processamento assíncrono

Utilize o cabeçalho Idempotency-Key para desduplicar a mesma operação no mesmo instantâneo de artigo e devolver a resposta memorizada. delivery_id identifica apenas cada tentativa. Guarde também a correspondência article.id para impedir criações duplicadas entre operações diferentes. O cabeçalho X-Sorank-Article-Revision permite recusar uma versão antiga recebida após uma versão mais recente. Se o processamento não estiver concluído, responda HTTP 202 com "sorank_webhook_version": 2, "status": "accepted" e, se conhecido, "article_url". Um 202 nunca confirma a publicação. Para permitir ao SORANK verificar posteriormente esta operação assíncrona, adicione apenas após a sua aplicação efetiva esta etiqueta no HTML público do artigo:
Substitua o valor pelo do cabeçalho Idempotency-Key recebido. Não o adicione aquando da receção: a página antiga não prova a nova atualização. Sem esta prova, a verificação fica pendente e expira. Se a sua ferramenta não conseguir publicar esta etiqueta, conclua a publicação antes de devolver a resposta 200/201.

​
Migrar uma integração existente

Uma resposta 200 vazia ou textual continua a ser compatível com a entrega histórica, mas não ativa as atualizações. Adapte a sua rota, clique em Test e depois em Save webhook: o SORANK volta a testar as capacidades do lado do servidor ao guardar. Uma alteração de URL ou de secret invalida as verificações antigas em curso. Para atualizar artigos já publicados, reconstitua a correspondência article.id do lado do CMS; o SORANK não consegue determiná-la.

​
Evento: article.published

Acionado sempre que publica um artigo a partir do SORANK. É o evento que o seu endpoint de produção deve processar para criar a publicação no seu CMS ou acionar o seu fluxo de automatização. ‍

​
Evento: webhook.test

Acionado quando clica no botão Test no SORANK para verificar que o seu endpoint está acessível. A carga útil utiliza valores fictícios (id contém apenas zeros, featured_image é omitido, images está vazio) para que a sua integração possa ignorá-la com segurança ou utilizá-la para confirmar a conectividade sem criar uma publicação real. ‍

​
Referência dos campos

  • event, article.published, article.updated ou webhook.test. Baseie-se neste campo para encaminhar a carga útil.
  • delivery_id, UUID único para rastrear cada tentativa de entrega. Para desduplicar uma operação, utilize o cabeçalho Idempotency-Key.
  • timestamp, carimbo de data/hora ISO 8601 UTC do momento em que o evento foi emitido.
  • article.id, identificador único do artigo no SORANK.
  • article.title, o H1 / título do artigo.
  • article.slug, slug adaptado a URLs, em minúsculas e com hífenes.
  • article.meta_description, meta-descrição SEO, pronta a inserir na sua etiqueta <meta name="description">.
  • article.focus_keyphrase, expressão-chave alvo principal utilizada para o artigo.
  • article.content, corpo completo do artigo em HTML, incluindo títulos, parágrafos, listas e etiquetas de imagens inline.
  • article.featured_image, objeto de imagem de destaque com url, alt e placement. Pode estar presente em article.published e article.updated.
  • article.images, conjunto de imagens adicionais no corpo. Cada entrada inclui url, alt e placement. Pode estar vazio.
  • article.word_count, número total de palavras do corpo do artigo.
  • article.keyword, idêntico à expressão-chave alvo, mantido como campo separado para integrações retrocompatíveis.
  • article.language, etiqueta de idioma BCP 47 (por exemplo en-US, fr-FR).

​
Casos de utilização comuns

  • Zapier: utilize um acionador “Catch Hook” para transferir os artigos para milhares de aplicações como WordPress, Notion, Airtable ou Google Sheets.
  • Make: utilize um módulo Webhooks para criar automatizações de publicação personalizadas em várias etapas.
  • n8n: ligue um nó Webhook a um fluxo que cria a publicação no seu CMS headless ou no seu back-office.
  • Backend personalizado: envie os artigos diretamente para a sua própria API para publicar num site desenvolvido à medida, num CMS headless como Sanity ou Strapi, ou em qualquer ferramenta interna.

​
Dicas

  • Clique sempre em Test antes de guardar para confirmar que o seu endpoint aceita o pedido e devolve uma resposta 2xx.
  • Baseie-se no campo event do lado do servidor para que as chamadas webhook.test nunca criem publicações reais.
  • Utilize Idempotency-Key para desduplicar uma operação e article.id para localizar o mesmo artigo no seu CMS.
  • Mantenha o seu Secret token privado, verifique o cabeçalho Authorization em cada pedido e renove o secret regularmente.
  • Utilize um endpoint HTTPS para manter os dados dos artigos seguros durante o trânsito.
  • Uma vez ligado, cada artigo publicado no SORANK será automaticamente enviado para o seu URL de webhook.

​
🔄 Por que razão os seus artigos podem não aparecer (causas de falha)

Como o webhook apenas entrega os dados, um “sucesso” no SORANK não garante que o artigo está publicado no seu site. Verifique cada etapa para localizar o bloqueio. Eis os pontos a examinar.

​
Causas do lado da sua integração

  • A sua chave de API do CMS é apenas de leitura em vez de leitura e escrita, este é um dos problemas mais frequentes. Se as credenciais que o seu código utiliza para escrever no seu CMS (Sanity, Strapi, Contentful ou qualquer backend headless) apenas dispõem de permissões de consulta / leitura, o seu endpoint receberá o JSON mas falhará silenciosamente ao criar a publicação. Gere uma chave com acesso de escrita e atualize-a na sua integração.
  • O seu código recebe o JSON mas nunca o envia para o seu CMS, receber a carga útil representa apenas metade do trabalho. Certifique-se de que o seu endpoint mapeia efetivamente os campos do SORANK e cria a publicação no seu CMS ou na sua base de dados. Registe a carga útil recebida e confirme que a sua chamada de publicação é executada e bem-sucedida.
  • O mapeamento dos campos está incorreto, se o seu código espera nomes de campos diferentes dos presentes na carga útil, a publicação pode ser criada vazia ou rejeitada. Verifique que está a ler article.title, article.slug, article.content, etc., exatamente como documentado acima.
  • O seu endpoint devolve um 2xx mas gera um erro posteriormente, se acusar a receção do pedido antes de o processar de forma assíncrona, uma falha posterior na sua lógica de publicação não será visível para o SORANK. Consulte os seus próprios registos de servidor para as detetar.

​
Causas do lado da entrega

  • O seu endpoint de webhook deixou de responder (servidor offline), coloque o seu servidor novamente online e verifique que o URL responde normalmente.
  • O URL do webhook foi alterado mas não foi atualizado no SORANK, atualize o URL nas definições de integração do SORANK.
  • Regenerou o seu secret de webhook do seu lado, atualize o secret no SORANK para que corresponda ao que o seu servidor espera agora no cabeçalho Authorization.
  • O seu endpoint devolve um erro que o SORANK não consegue interpretar, consulte os seus registos de servidor para identificar o problema e corrija-o do lado do seu webhook.
  • Uma firewall no seu servidor bloqueia os nossos pedidos, adicione os endereços IP do SORANK à lista autorizada da sua firewall, ou autorize o User-Agent SORANK-Webhook/1.0.
  • O seu endpoint demora mais de 30 segundos a responder, otimize o seu endpoint para responder mais rapidamente, ou acuse a receção do pedido imediatamente e processe-o de forma assíncrona.
Quando o SORANK não consegue entregar um artigo ao seu endpoint, o seu agendador é automaticamente colocado em pausa e recebe um e-mail. Assim que corrigir o problema e voltar a ligar o seu webhook no SORANK, o seu agendador retoma automaticamente. O seu artigo já está gerado e armazenado em segurança, nada se perde.

​
🚀 Não é programador? Aloje antes o seu blog no SORANK

O webhook obriga-o a escrever e a manter código que capta o JSON e o publica no seu site. Se construiu o seu site com uma ferramenta no-code ou uma ferramenta de IA, como Lovable, Base44, Cursor ou Claude Code, e não está em condições de desenvolver e alojar um endpoint que capta o webhook e publica o artigo, existe uma via muito mais simples. Criámos uma solução que lhe permite alojar automaticamente o seu blog no seu próprio subdomínio, diretamente no SORANK. Sem código, sem endpoint a manter, sem webhook a captar. Descubra como funciona aqui: Aloje o seu blog no SORANK.

​
Procura antes uma integração nativa?

Se a sua plataforma for suportada, um conector direto é mais simples do que o webhook. Consulte os nossos guias para Webflow, Shopify, WordPress.org, WordPress.com, Wix e HubSpot.

​
O problema persiste após verificação?

Se verificou os pontos acima e a publicação continua a falhar, responda diretamente ao e-mail que recebeu: a nossa equipa irá analisar o que se passa na sua conta. Os seus artigos continuam gerados e armazenados em segurança no SORANK. Assim que a ligação for restabelecida, o seu agendador retoma automaticamente onde parou.