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
- Clique na sua fotografia de perfil no canto superior direito e selecione Configurações.
- Abra o separador Integrações.
- Desça até ao cartão Webhook e clique em Conectar o seu site.
Passo 2: Configurar o seu endpoint
- 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).
- Opcionalmente, adicione um Secret token se o seu endpoint exigir autenticação. O Sorank irá incluí-lo como um token
Bearerno cabeçalhoAuthorization, para que o seu servidor possa verificar que a chamada provém do Sorank. - Clique em Test para enviar um payload de exemplo (tipo de evento
webhook.test) e confirmar que o seu endpoint responde corretamente. - 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)
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.
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.
Referência dos campos
- event, Tipo de evento.
article.publishedouwebhook.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,alteplacement. Presente apenas em eventosarticle.published. - article.images, Lista de imagens adicionais no corpo. Cada entrada tem
url,alteplacement. 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
eventdo lado do servidor para que as chamadaswebhook.testnunca criem publicações reais. - Utilize o
delivery_idcomo chave de idempotência para evitar publicar o mesmo artigo duas vezes em retentativas. - Mantenha o seu Secret token privado, verifique o cabeçalho
Authorizationem 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.