Connect Webhook Guide | GroMach

Visão Geral

A integração via Webhook permite que você receba dados de artigos do GroMach e os processe no seu próprio sistema backend. Quando você publica um artigo, o GroMach envia uma requisição POST para o endpoint configurado com o conteúdo do artigo.

Passo 1: Configure Seu Endpoint de Webhook

Crie um endpoint HTTPS no seu servidor para receber as requisições do webhook. O endpoint deve:

Aceitar requisições POST: Todos os dados do webhook são enviados via POST
Usar HTTPS: Por segurança, apenas URLs HTTPS são suportadas
Retornar status 2xx: Retorne um código de status de sucesso para confirmar o recebimento

Passo 2: Implemente a Verificação de Assinatura

O GroMach assina todas as requisições de webhook usando HMAC-SHA256. Você deve verificar esta assinatura para garantir que as requisições são autênticas.

Cada requisição inclui estes cabeçalhos:

x-webhook-signature: Assinatura HMAC-SHA256 do corpo da requisição
x-webhook-timestamp: Timestamp ISO 8601 de quando a requisição foi enviada
Content-Type: application/json

Aqui está um exemplo de verificação de assinatura em Node.js:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(computedSignature, 'hex')
  );
}

// In your endpoint handler:
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifySignature(payload, signature, YOUR_SECRET_KEY)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process the webhook...
  res.json({ success: true });
});

Passo 3: Formato do Payload do Webhook

Quando um artigo é publicado, o GroMach envia um payload com a seguinte estrutura:

{
  "event_type": "publish_articles",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "articles": [
      {
        "id": "article-uuid-123",
        "slug": "my-article-slug",
        "title": "Article Title",
        "excerpt": "Brief description of the article...",
        "content_format": "markdown",
        "content": "# Full article content in markdown...",
        "status": "published",
        "published_at": "2024-01-15T10:30:00.000Z",
        "author_name": "Admin",
        "cover_image": "https://example.com/image.jpg",
        "meta_title": "SEO Title",
        "meta_description": "SEO meta description",
        "tags": ["seo", "marketing"]
      }
    ]
  }
}

Referência dos Campos do Artigo

id: Identificador único do artigo
slug: Identificador amigável para URL do artigo
title: Título do artigo
excerpt: Breve descrição ou resumo
content_format: "markdown" ou "html"
content: Conteúdo completo do artigo
status: Status de publicação (draft, published, archived)
published_at: Timestamp de publicação em ISO 8601
author_name: Nome de exibição do autor
cover_image: URL da imagem de capa (se disponível)
meta_title: Título SEO para motores de busca
meta_description: Meta descrição SEO
tags: Array de strings de tags

Passo 4: Configure no GroMach

Na página de integrações do GroMach, preencha as seguintes informações:

Nome (Opcional): Um nome amigável para identificar este webhook
URL do Webhook: A URL do seu endpoint HTTPS (ex.: https://seu-site.com/api/webhook)
Chave Secreta: Uma string secreta usada para assinar requisições (mantenha-a segura!)
Status de Publicação: Escolha se os artigos são enviados como "published" ou "draft"

Importante

Mantenha sua Chave Secreta segura e nunca a exponha em código cliente. Use variáveis de ambiente para armazená-la com segurança no seu servidor.

Testando Seu Webhook

Antes de criar a integração, você pode testar a conexão do seu webhook usando o botão "Testar Conexão". O GroMach enviará uma requisição de teste para verificar se seu endpoint está configurado corretamente.

Requisitos do Teste

Para o teste passar, seu endpoint deve:

1. Verificar a assinatura: Use a chave secreta para verificar o cabeçalho X-Webhook-Signature
2. Retornar resposta de sucesso: Retorne uma resposta JSON com { "success": true }

O payload de teste se parece com:

{
  "event_type": "test",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "message": "This is a test webhook from Gromach SEO",
    "integration_name": "My Webhook"
  }
}

Aqui está um exemplo completo de como seu endpoint de teste deve lidar com a requisição:

const crypto = require('crypto');

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);

  // Step 1: Verify the signature
  const computedSignature = crypto
    .createHmac('sha256', YOUR_SECRET_KEY)
    .update(payload)
    .digest('hex');

  const isValid = crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(computedSignature, 'hex')
  );

  if (!isValid) {
    return res.status(401).json({
      success: false,
      error: 'Invalid signature'
    });
  }

  // Step 2: Process based on event type
  if (req.body.event_type === 'test') {
    // Test connection - just return success
    return res.json({ success: true });
  }

  if (req.body.event_type === 'publish_articles') {
    // Process articles...
    const articles = req.body.data.articles;
    // Save to your database, etc.
    return res.json({ success: true });
  }

  res.json({ success: true });
});

Por que a verificação de assinatura é necessária

A verificação de assinatura garante que as requisições de webhook são genuinamente do GroMach e não foram adulteradas. Esta é uma prática de segurança recomendada que protege seu endpoint de requisições não autorizadas.

Solução de Problemas

Teste de conexão falha

• Verifique se a URL do seu endpoint está correta e usa HTTPS
• Certifique-se de que seu servidor está acessível pela internet
• Confirme que seu endpoint retorna um código de status 2xx

Falha na verificação de assinatura

• Certifique-se de estar usando a Chave Secreta exata do GroMach
• Verifique se você está fazendo hash do corpo bruto da requisição, não de um objeto parseado
• Use comparação timing-safe para prevenir ataques de temporização

Artigos não aparecem

• Verifique os logs do seu servidor para quaisquer erros de processamento
• Confirme se o status do artigo corresponde ao seu fluxo de trabalho esperado
• Certifique-se de que as operações do banco de dados estão sendo concluídas com sucesso

Guia de integração Webhook