Connect Webhook Guide | GroMach

Overzicht

De Webhook-integratie stelt je in staat om artikelgegevens van GroMach te ontvangen en te verwerken in je eigen backend-systeem. Wanneer je een artikel publiceert, stuurt GroMach een POST-verzoek naar het door jou geconfigureerde eindpunt met de artikelinhoud.

Stap 1: Stel je Webhook-eindpunt in

Maak een HTTPS-eindpunt op je server aan om webhook-verzoeken te ontvangen. Het eindpunt moet:

POST-verzoeken accepteren: Alle webhook-gegevens worden via POST verzonden
HTTPS gebruiken: Voor de beveiliging worden alleen HTTPS-URL's ondersteund
2xx-status retourneren: Retourneer een successtatuscode om ontvangst te bevestigen

Stap 2: Implementeer handtekeningverificatie

GroMach ondertekent alle webhook-verzoeken met HMAC-SHA256. Je moet deze handtekening verifiëren om ervoor te zorgen dat verzoeken authentiek zijn.

Elk verzoek bevat deze headers:

x-webhook-signature: HMAC-SHA256 handtekening van de request body
x-webhook-timestamp: ISO 8601 tijdstempel van wanneer het verzoek werd verzonden
Content-Type: application/json

Hier is een voorbeeld van handtekeningverificatie in 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 });
});

Stap 3: Webhook Payload-formaat

Wanneer een artikel wordt gepubliceerd, stuurt GroMach een payload met de volgende structuur:

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

Artikelvelden Referentie

id: Unieke identificatie voor het artikel
slug: URL-vriendelijke identificatie voor het artikel
title: Artikeltitel
excerpt: Korte beschrijving of samenvatting
content_format: "markdown" of "html"
content: Volledige artikelinhoud
status: Publicatiestatus (draft, published, archived)
published_at: ISO 8601 publicatietijdstempel
author_name: Weergavenaam van de auteur
cover_image: URL van de omslagafbeelding (indien beschikbaar)
meta_title: SEO-titel voor zoekmachines
meta_description: SEO-metabeschrijving
tags: Array van tag-strings

Stap 4: Configureer in GroMach

Vul op de GroMach-integratiepagina de volgende informatie in:

Naam (Optioneel): Een vriendelijke naam om deze webhook te identificeren
Webhook-URL: Je HTTPS-eindpunt URL (bijv., https://jouw-site.com/api/webhook)
Geheime Sleutel: Een geheime string die wordt gebruikt om verzoeken te ondertekenen (houd deze veilig!)
Publicatiestatus: Kies of artikelen worden verzonden als "published" of "draft"

Belangrijk

Houd je Geheime Sleutel veilig en stel deze nooit bloot in client-side code. Gebruik omgevingsvariabelen om deze veilig op je server op te slaan.

Je Webhook testen

Voordat je de integratie aanmaakt, kun je je webhook-verbinding testen met de knop "Test Verbinding". GroMach stuurt een testverzoek om te verifiëren dat je eindpunt correct is geconfigureerd.

Testvereisten

Om de test te laten slagen, moet je eindpunt:

1. De handtekening verifiëren: Gebruik de geheime sleutel om de X-Webhook-Signature header te verifiëren
2. Succesrespons retourneren: Retourneer een JSON-respons met { "success": true }

De test-payload ziet er als volgt uit:

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

Hier is een compleet voorbeeld van hoe je test-eindpunt het verzoek moet afhandelen:

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

Waarom handtekeningverificatie vereist is

Handtekeningverificatie zorgt ervoor dat de webhook-verzoeken echt van GroMach komen en niet zijn gemanipuleerd. Dit is een best practice voor beveiliging die je eindpunt beschermt tegen ongeautoriseerde verzoeken.

Probleemoplossing

Verbindingstest mislukt

• Controleer of je eindpunt-URL correct is en HTTPS gebruikt
• Zorg ervoor dat je server toegankelijk is vanaf het internet
• Controleer of je eindpunt een 2xx-statuscode retourneert

Handtekeningverificatie mislukt

• Zorg ervoor dat je de exacte Geheime Sleutel van GroMach gebruikt
• Verifieer dat je de onbewerkte request body hasht, niet een geparsed object
• Gebruik timing-safe vergelijking om timing-aanvallen te voorkomen

Artikelen verschijnen niet

• Controleer je serverlogs op verwerkingsfouten
• Verifieer dat de artikelstatus overeenkomt met je verwachte workflow
• Zorg ervoor dat je database-operaties succesvol worden voltooid

Webhook-integratiehandleiding