Connect Webhook Guide | GroMach

Przegląd

Integracja Webhook pozwala na odbieranie danych artykułów z GroMach i przetwarzanie ich w Twoim własnym systemie backend. Gdy publikujesz artykuł, GroMach wysyła żądanie POST do skonfigurowanego punktu końcowego z treścią artykułu.

Krok 1: Skonfiguruj Punkt Końcowy Webhook

Utwórz punkt końcowy HTTPS na swoim serwerze, aby odbierać żądania webhook. Punkt końcowy musi:

Akceptować żądania POST: Wszystkie dane webhook są wysyłane poprzez POST
Używać HTTPS: Ze względów bezpieczeństwa obsługiwane są tylko adresy URL HTTPS
Zwracać status 2xx: Zwróć kod statusu sukcesu, aby potwierdzić odbiór

Krok 2: Implementacja Weryfikacji Podpisu

GroMach podpisuje wszystkie żądania webhook używając HMAC-SHA256. Powinieneś zweryfikować ten podpis, aby upewnić się, że żądania są autentyczne.

Każde żądanie zawiera następujące nagłówki:

x-webhook-signature: Podpis HMAC-SHA256 treści żądania
x-webhook-timestamp: Znacznik czasu ISO 8601 wysłania żądania
Content-Type: application/json

Oto przykład weryfikacji podpisu w 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 });
});

Krok 3: Format Danych Webhook

Gdy artykuł jest publikowany, GroMach wysyła dane o następującej strukturze:

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

Opis Pól Artykułu

id: Unikalny identyfikator artykułu
slug: Przyjazny dla adresu URL identyfikator artykułu
title: Tytuł artykułu
excerpt: Krótki opis lub streszczenie
content_format: Albo "markdown" albo "html"
content: Pełna treść artykułu
status: Status publikacji (draft, published, archived)
published_at: Znacznik czasu publikacji w formacie ISO 8601
author_name: Wyświetlana nazwa autora
cover_image: Adres URL obrazu okładki (jeśli dostępny)
meta_title: Tytuł SEO dla wyszukiwarek
meta_description: Meta opis SEO
tags: Tablica tagów tekstowych

Krok 4: Konfiguracja w GroMach

Na stronie integracji GroMach wypełnij następujące informacje:

Nazwa (Opcjonalna): Przyjazna nazwa do identyfikacji tego webhooka
URL Webhooka: Adres URL Twojego punktu końcowego HTTPS (np. https://your-site.com/api/webhook)
Klucz Tajny: Tajny ciąg znaków używany do podpisywania żądań (zachowaj go w bezpiecznym miejscu!)
Status Publikacji: Wybierz, czy artykuły są wysyłane jako "published" czy "draft"

Ważne

Zachowaj swój Klucz Tajny w bezpiecznym miejscu i nigdy nie ujawniaj go w kodzie po stronie klienta. Używaj zmiennych środowiskowych, aby przechowywać go bezpiecznie na serwerze.

Testowanie Webhooka

Przed utworzeniem integracji możesz przetestować połączenie webhook za pomocą przycisku "Testuj Połączenie". GroMach wyśle testowe żądanie, aby zweryfikować, czy Twój punkt końcowy jest poprawnie skonfigurowany.

Wymagania Testu

Aby test się powiódł, Twój punkt końcowy musi:

1. Zweryfikować podpis: Użyj klucza tajnego do weryfikacji nagłówka X-Webhook-Signature
2. Zwrócić odpowiedź sukcesu: Zwróć odpowiedź JSON z { "success": true }

Testowe dane wyglądają następująco:

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

Oto kompletny przykład, jak Twój punkt końcowy testowy powinien obsłużyć żądanie:

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

Dlaczego weryfikacja podpisu jest wymagana

Weryfikacja podpisu zapewnia, że żądania webhook pochodzą rzeczywiście z GroMach i nie zostały zmodyfikowane. Jest to najlepsza praktyka bezpieczeństwa, która chroni Twój punkt końcowy przed nieautoryzowanymi żądaniami.

Rozwiązywanie Problemów

Test połączenia nie powiódł się

• Zweryfikuj, czy adres URL punktu końcowego jest poprawny i używa HTTPS
• Upewnij się, że Twój serwer jest dostępny z internetu
• Sprawdź, czy Twój punkt końcowy zwraca kod statusu 2xx

Weryfikacja podpisu nie powiodła się

• Upewnij się, że używasz dokładnego Klucza Tajnego z GroMach
• Zweryfikuj, że hashujesz surową treść żądania, a nie sparsowany obiekt
• Użyj porównania bezpiecznego czasowo, aby zapobiec atakom czasowym

Artykuły nie pojawiają się

• Sprawdź logi serwera pod kątem błędów przetwarzania
• Zweryfikuj, czy status artykułu odpowiada oczekiwanemu przepływowi pracy
• Upewnij się, że operacje na bazie danych kończą się pomyślnie

Przewodnik integracji Webhook