Connect Webhook Guide | GroMach

Übersicht

Die Webhook-Integration ermöglicht es Ihnen, Artikeldaten von GroMach zu empfangen und in Ihrem eigenen Backend-System zu verarbeiten. Wenn Sie einen Artikel veröffentlichen, sendet GroMach eine POST-Anfrage an Ihren konfigurierten Endpunkt mit dem Artikelinhalt.

Schritt 1: Richten Sie Ihren Webhook-Endpunkt ein

Erstellen Sie einen HTTPS-Endpunkt auf Ihrem Server, um Webhook-Anfragen zu empfangen. Der Endpunkt muss:

POST-Anfragen akzeptieren: Alle Webhook-Daten werden per POST gesendet
HTTPS verwenden: Aus Sicherheitsgründen werden nur HTTPS-URLs unterstützt
2xx-Status zurückgeben: Geben Sie einen Erfolgsstatuscode zurück, um den Empfang zu bestätigen

Schritt 2: Implementieren Sie die Signaturverifizierung

GroMach signiert alle Webhook-Anfragen mit HMAC-SHA256. Sie sollten diese Signatur verifizieren, um sicherzustellen, dass die Anfragen authentisch sind.

Jede Anfrage enthält diese Header:

x-webhook-signature: HMAC-SHA256-Signatur des Anfragekörpers
x-webhook-timestamp: ISO 8601-Zeitstempel, wann die Anfrage gesendet wurde
Content-Type: application/json

Hier ist ein Beispiel für die Signaturverifizierung 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 });
});

Schritt 3: Webhook-Payload-Format

Wenn ein Artikel veröffentlicht wird, sendet GroMach eine Payload mit folgender 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"]
      }
    ]
  }
}

Artikel-Felder-Referenz

id: Eindeutige Kennung für den Artikel
slug: URL-freundliche Kennung für den Artikel
title: Artikeltitel
excerpt: Kurze Beschreibung oder Zusammenfassung
content_format: Entweder "markdown" oder "html"
content: Vollständiger Artikelinhalt
status: Veröffentlichungsstatus (draft, published, archived)
published_at: ISO 8601-Veröffentlichungszeitstempel
author_name: Anzeigename des Autors
cover_image: URL des Titelbilds (falls verfügbar)
meta_title: SEO-Titel für Suchmaschinen
meta_description: SEO-Meta-Beschreibung
tags: Array von Tag-Strings

Schritt 4: Konfiguration in GroMach

Füllen Sie auf der GroMach-Integrationsseite die folgenden Informationen aus:

Name (Optional): Ein freundlicher Name zur Identifizierung dieses Webhooks
Webhook-URL: Ihre HTTPS-Endpunkt-URL (z.B. https://ihre-seite.com/api/webhook)
Geheimer Schlüssel: Eine geheime Zeichenfolge zum Signieren von Anfragen (halten Sie diese sicher!)
Veröffentlichungsstatus: Wählen Sie, ob Artikel als "published" oder "draft" gesendet werden

Wichtig

Halten Sie Ihren geheimen Schlüssel sicher und legen Sie ihn niemals in clientseitigem Code offen. Verwenden Sie Umgebungsvariablen, um ihn sicher auf Ihrem Server zu speichern.

Testen Sie Ihren Webhook

Bevor Sie die Integration erstellen, können Sie Ihre Webhook-Verbindung mit der Schaltfläche "Verbindung testen" testen. GroMach sendet eine Testanfrage, um zu verifizieren, dass Ihr Endpunkt ordnungsgemäß konfiguriert ist.

Testanforderungen

Damit der Test erfolgreich ist, muss Ihr Endpunkt:

1. Die Signatur verifizieren: Verwenden Sie den geheimen Schlüssel, um den X-Webhook-Signature-Header zu verifizieren
2. Erfolgsantwort zurückgeben: Geben Sie eine JSON-Antwort mit { "success": true } zurück

Die Test-Payload sieht folgendermaßen aus:

{
  "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 ist ein vollständiges Beispiel, wie Ihr Test-Endpunkt die Anfrage verarbeiten sollte:

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

Warum die Signaturverifizierung erforderlich ist

Die Signaturverifizierung stellt sicher, dass die Webhook-Anfragen wirklich von GroMach stammen und nicht manipuliert wurden. Dies ist eine bewährte Sicherheitspraxis, die Ihren Endpunkt vor unbefugten Anfragen schützt.

Fehlerbehebung

Verbindungstest schlägt fehl

• Überprüfen Sie, ob Ihre Endpunkt-URL korrekt ist und HTTPS verwendet
• Stellen Sie sicher, dass Ihr Server aus dem Internet erreichbar ist
• Prüfen Sie, dass Ihr Endpunkt einen 2xx-Statuscode zurückgibt

Signaturverifizierung schlägt fehl

• Stellen Sie sicher, dass Sie den exakten geheimen Schlüssel aus GroMach verwenden
• Verifizieren Sie, dass Sie den rohen Anfragekörper hashen, nicht ein geparste Objekt
• Verwenden Sie einen timing-sicheren Vergleich, um Timing-Angriffe zu verhindern

Artikel werden nicht angezeigt

• Überprüfen Sie Ihre Serverprotokolle auf Verarbeitungsfehler
• Stellen Sie sicher, dass der Artikelstatus Ihrem erwarteten Workflow entspricht
• Prüfen Sie, ob Ihre Datenbankoperationen erfolgreich abgeschlossen werden

Webhook-Integrationsanleitung