Webhooks

Não tem uma integração nativa do Sorank 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 programado, para que possa publicar o seu conteúdo onde precisar.

Como funciona

Quando publica um artigo no Sorank, enviamos um pedido POST com um payload JSON estruturado para o URL que configurou. O seu endpoint ou ferramenta de automação pode então processar o payload e criar a publicação no seu blogue, site personalizado ou qualquer outra ferramenta que aceite pedidos HTTP recebidos.

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

Esta é a coisa mais importante a compreender sobre o conector Webhook. Do nosso lado, o Sorank reúne tudo o que precisa dentro do JSON (título, slug, corpo HTML completo, meta descrição, imagens, idioma e muito mais) e dispara-o para o seu URL. Assim que esse JSON é enviado com sucesso, o Sorank marca a entrega como bem-sucedida.

Esse estado de "sucesso" confirma apenas uma coisa: os dados saíram do Sorank e o seu endpoint aceitou-os. Não temos forma de saber o que acontece a seguir do seu lado. Não conseguimos detetar se o seu código leu efetivamente o JSON, mapeou os campos corretamente ou colocou o artigo em linha no seu site.

Por outras palavras, o webhook é apenas um mecanismo de entrega dos dados. Recebê-los, analisá-los e publicá-los no seu CMS é inteiramente da sua responsabilidade. Se o artigo não aparecer no seu blogue mesmo que o Sorank mostre "sucesso", o problema está quase sempre na forma como a sua integração captura e processa o payload, e não na entrega em si.

Passo 1: Abrir a integração Webhook

1. Clique na sua fotografia de perfil no canto superior direito e selecione Configurações.
2. Abra o separador Integrações.
3. Desça até ao cartão Webhook e clique em Conectar o seu site.

Passo 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. Opcionalmente, adicione um Secret token se o seu endpoint exigir autenticação. O Sorank irá incluí-lo como um 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 um payload 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.

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 vai receber:

• Método: POST
• Content-Type: application/json
• User-Agent: SORANK-Webhook/1.0
• Authorization: Bearer {webhook_secret} (opcional, enviado apenas se tiver configurado um secret nas configuraçõ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 remetente desconhecido.

Estrutura do payload do webhook

O Sorank emite dois tipos de eventos de webhook. Ambos partilham o mesmo envelope de nível superior (event, delivery_id, timestamp, article), pelo que a sua integração só precisa de comutar no campo event para encaminhar o payload.

Evento: article.published

Disparado sempre que publica um artigo a partir do Sorank. Este é 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 automação.

‍

{
  "event": "article.published",
  "delivery_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-05-21T10:30:45.123456Z",
  "article": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Best SEO Practices for 2025",
    "slug": "best-seo-practices-2025",
    "meta_description": "Discover the best SEO practices for 2025.",
    "focus_keyphrase": "seo practices",
    "content": "<h1>Best SEO Practices</h1><p>Article body content here...</p>",
    "featured_image": {
      "url": "https://storage.example.com/image.jpg",
      "alt": "Best SEO Practices for 2025",
      "placement": "hero"
    },
    "images": [
      {
        "url": "https://storage.example.com/image2.jpg",
        "alt": "SEO diagram",
        "placement": "body"
      }
    ],
    "word_count": 1500,
    "keyword": "seo practices",
    "language": "en-US"
  }
}

Evento: webhook.test

Disparado quando clica no botão Test no Sorank para verificar se o seu endpoint está acessível. O payload utiliza valores fictícios (id é só zeros, featured_image é omitido, images está vazio), para que a sua integração possa ignorá-lo em segurança ou utilizá-lo para confirmar a conetividade sem criar uma publicação real.‍

{

  "event": "webhook.test",

  "delivery_id": "550e8400-e29b-41d4-a716-446655440000",

  "timestamp": "2025-05-21T10:30:45.123456Z",

  "article": {

    "id": "00000000-0000-0000-0000-000000000000",

    "title": "Test Article - Webhook Connectivity Check",

    "slug": "test-article-webhook-check",

    "meta_description": "This is a test payload to verify webhook connectivity.",

    "focus_keyphrase": "webhook test",

    "content": "<h2>Test Article</h2><p>This is a test payload sent by SORANK to verify your webhook endpoint is working correctly.</p>",

    "images": [],

    "word_count": 20,

    "keyword": "webhook test",

    "language": "en-US"

  }

}

Referência dos campos

• event, Tipo de evento. article.published ou webhook.test. Comute neste campo para encaminhar o payload.
• delivery_id, UUID único para cada tentativa de entrega. Guarde-o do seu lado para eliminar duplicados em retentativas e proteger-se contra publicações duplicadas.
• timestamp, Carimbo temporal UTC em ISO 8601 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 compatível com URL, em minúsculas e com hífenes.
• article.meta_description, Meta descrição SEO, pronta para colocar na sua etiqueta <meta name="description">.
• article.focus_keyphrase, Frase-chave alvo principal utilizada para o artigo.
• article.content, Corpo completo do artigo em HTML, incluindo títulos, parágrafos, listas e etiquetas de imagem em linha.
• article.featured_image, Objeto da imagem de capa com url, alt e placement. Presente apenas em eventos article.published.
• article.images, Lista de imagens adicionais no corpo. Cada entrada tem url, alt e placement. Pode estar vazia.
• article.word_count, Contagem total de palavras do corpo do artigo.
• article.keyword, Igual à frase-chave principal, 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 encaminhar artigos para milhares de aplicações, como WordPress, Notion, Airtable ou Google Sheets.
• Make: utilize um módulo Webhooks para construir automações de publicação personalizadas e com vários passos.
• n8n: ligue um nó Webhook a um fluxo que cria a publicação no seu CMS headless ou back office.
• Backend personalizado: envie artigos diretamente para a sua própria API para publicar num site programado à mão, num CMS headless como o Sanity ou o 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.
• Comute no campo event do lado do servidor para que as chamadas webhook.test nunca criem publicações reais.
• Utilize o delivery_id como chave de idempotência para evitar publicar o mesmo artigo duas vezes em retentativas.
• Mantenha o seu Secret token privado, verifique o cabeçalho Authorization em cada pedido e rode o secret regularmente.
• Utilize um endpoint HTTPS para manter os dados do artigo seguros em trânsito.
• Uma vez conectado, cada artigo publicado no Sorank será automaticamente enviado para o seu URL de webhook.

🔄 Porque é que 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 esteja em linha no seu site. Quando algo corre mal, é quase sempre do lado de receção. Eis as causas mais comuns e como as resolver.

Causas do lado da sua integração

• A chave de API do seu CMS é só 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) tiverem apenas permissões de visualização / 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 o payload é 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 base de dados. Registe o payload recebido e confirme que a sua chamada de publicação é executada e bem-sucedida.
• O mapeamento de campos está incorreto, Se o seu código espera nomes de campos diferentes dos que estão no payload, a publicação pode ser criada vazia ou rejeitada. Verifique novamente que lê article.title, article.slug, article.content, etc., exatamente como documentado acima.
• O seu endpoint devolve 2xx mas lança um erro depois, Se confirmar o 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 registos do seu próprio servidor para detetar estas situações.

Causas do lado da entrega

• O seu endpoint de webhook já não responde (servidor offline), Coloque o seu servidor novamente em linha e verifique que o URL responde normalmente.
• O URL do webhook mudou mas não foi atualizado no Sorank, Atualize o URL nas configurações da sua integração no Sorank.
• Regenerou o secret do seu webhook do seu lado, Atualize o secret no Sorank para que corresponda ao que o seu servidor agora espera no cabeçalho Authorization.
• O seu endpoint devolve um erro que o Sorank não consegue interpretar, Consulte os registos do seu servidor para identificar o problema e, em seguida, corrija-o do lado do seu webhook.
• Uma firewall no seu servidor está a bloquear os nossos pedidos, Coloque os IPs do Sorank na lista de permissões 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 que responda mais depressa, ou confirme o 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 receberá um email. Assim que resolver o problema e voltar a conectar o seu webhook no Sorank, o seu agendador retoma por si só. O seu artigo já está gerado e guardado em segurança, nada se perde.

🚀 Não é programador? Aloje o seu blogue no Sorank

O webhook exige que escreva e mantenha código que captura o JSON e o publica no seu site. Se construiu o seu site com uma ferramenta no-code ou de IA, como o Lovable, o Base44, o Cursor ou o Claude Code, e não consegue desenvolver e alojar um endpoint que capture o webhook e publique o artigo, existe um caminho muito mais simples.

Criámos uma solução em que pode alojar automaticamente o seu blogue no seu próprio subdomínio, diretamente no Sorank. Sem código, sem endpoint para manter, sem webhook para capturar. Saiba como funciona aqui: Aloje o seu blogue no Sorank.

Procura antes uma integração nativa?

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

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

Se já verificou os pontos acima e a publicação continua a falhar, responda diretamente ao email que recebeu: a nossa equipa irá analisar o que se passa na sua conta.

Os seus artigos permanecem gerados e guardados em segurança no Sorank. Assim que a ligação for restabelecida, o seu agendador retoma automaticamente de onde tinha ficado.