> ## Documentation Index > Fetch the complete documentation index at: https://sorank.com/llms.txt > Use this file to discover all available pages before exploring further. # Webhooks > Doc Sorank - Webhooks ## 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](/pt/documentation/host-your-blog-on-sorank). Se o seu CMS dispõe de um conector nativo, utilize o percurso apresentado em [publicar e exportar](/pt/documentation/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: ```json theme={null} { "sorank_webhook_version": 2, "capabilities": ["article.published", "article.updated"] } ``` 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](https://app.sorank.com/settings/integrations/publishing). 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: ```json theme={null} { "sorank_webhook_version": 2, "capabilities": ["article.published", "article.updated"] } ``` 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: ```json theme={null} { "sorank_webhook_version": 2, "status": "published", "article_url": "https://example.com/blog/mon-article" } ``` 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 ``. 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: ```html theme={null} ``` 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 ``. * **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](/pt/documentation/host-your-blog-on-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](/pt/documentation/conectar-o-webflow), [Shopify](/pt/documentation/conectar-o-shopify), [WordPress.org](/pt/documentation/conectar-o-wordpress-org), [WordPress.com](/pt/documentation/conectar-o-wordpress-com), [Wix](/pt/documentation/conectar-o-wix) e [HubSpot](/pt/documentation/usar-hubspot-com-sorank). ### 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.