Connect Webhook Guide | GroMach

Översikt

Webhook-integrationen gör det möjligt för dig att ta emot artikeldata från GroMach och bearbeta den i ditt eget backend-system. När du publicerar en artikel skickar GroMach en POST-förfrågan till din konfigurerade endpoint med artikelinnehållet.

Steg 1: Konfigurera din webhook-endpoint

Skapa en HTTPS-endpoint på din server för att ta emot webhook-förfrågningar. Endpointen måste:

Acceptera POST-förfrågningar: All webhook-data skickas via POST
Använda HTTPS: Av säkerhetsskäl stöds endast HTTPS-adresser
Returnera 2xx-status: Returnera en framgångsstatuskod för att bekräfta mottagning

Steg 2: Implementera signaturverifiering

GroMach signerar alla webhook-förfrågningar med HMAC-SHA256. Du bör verifiera denna signatur för att säkerställa att förfrågningarna är äkta.

Varje förfrågan innehåller dessa headers:

x-webhook-signature: HMAC-SHA256-signatur av förfrågningskroppen
x-webhook-timestamp: ISO 8601-tidsstämpel för när förfrågan skickades
Content-Type: application/json

Här är ett exempel på signaturverifiering i 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 });
});

Steg 3: Webhook-payload-format

När en artikel publiceras skickar GroMach en payload med följande struktur:

{
  "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"]
      }
    ]
  }
}

Referens för artikelfält

id: Unik identifierare för artikeln
slug: URL-vänlig identifierare för artikeln
title: Artikeltitel
excerpt: Kort beskrivning eller sammanfattning
content_format: Antingen "markdown" eller "html"
content: Fullständigt artikelinnehåll
status: Publiceringsstatus (draft, published, archived)
published_at: ISO 8601 publiceringstidsstämpel
author_name: Författarens visningsnamn
cover_image: URL till omslagsbilden (om tillgänglig)
meta_title: SEO-titel för sökmotorer
meta_description: SEO-metabeskrivning
tags: Array med taggsträngar

Steg 4: Konfigurera i GroMach

På GroMachs integrationssida fyller du i följande information:

Namn (Valfritt): Ett användarvänligt namn för att identifiera denna webhook
Webhook-URL: Din HTTPS-endpoint-URL (t.ex. https://your-site.com/api/webhook)
Hemlig nyckel: En hemlig sträng som används för att signera förfrågningar (håll denna säker!)
Publiceringsstatus: Välj om artiklar ska skickas som "published" eller "draft"

Viktigt

Håll din hemliga nyckel säker och exponera den aldrig i klientkod. Använd miljövariabler för att lagra den säkert på din server.

Testa din webhook

Innan du skapar integrationen kan du testa din webhook-anslutning med knappen "Testa anslutning". GroMach kommer att skicka en testförfrågan för att verifiera att din endpoint är korrekt konfigurerad.

Testkrav

För att testet ska lyckas måste din endpoint:

1. Verifiera signaturen: Använd den hemliga nyckeln för att verifiera X-Webhook-Signature-headern
2. Returnera framgångssvar: Returnera ett JSON-svar med { "success": true }

Test-payloaden ser ut så här:

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

Här är ett komplett exempel på hur din test-endpoint ska hantera förfrågan:

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 });
});

Varför signaturverifiering krävs

Signaturverifiering säkerställer att webhook-förfrågningarna verkligen kommer från GroMach och inte har manipulerats. Detta är en säkerhetspraxis som skyddar din endpoint från obehöriga förfrågningar.

Felsökning

Anslutningstestet misslyckas

• Verifiera att din endpoint-URL är korrekt och använder HTTPS
• Säkerställ att din server är tillgänglig från internet
• Kontrollera att din endpoint returnerar en 2xx-statuskod

Signaturverifiering misslyckas

• Se till att du använder den exakta hemliga nyckeln från GroMach
• Verifiera att du hashar den råa förfrågningskroppen, inte ett parsat objekt
• Använd tidssäker jämförelse för att förhindra timing-attacker

Artiklar visas inte

• Kontrollera dina serverloggar för eventuella bearbetningsfel
• Verifiera att artikelstatusen matchar ditt förväntade arbetsflöde
• Säkerställ att dina databasoperationer slutförs framgångsrikt