Panoramica
L'integrazione Webhook ti consente di ricevere i dati degli articoli da GroMach e di elaborarli nel tuo sistema backend. Quando pubblichi un articolo, GroMach invia una richiesta POST al tuo endpoint configurato con il contenuto dell'articolo.
Passo 1: Configura il Tuo Endpoint Webhook
Crea un endpoint HTTPS sul tuo server per ricevere le richieste webhook. L'endpoint deve:
- Accettare richieste POST: Tutti i dati webhook vengono inviati tramite POST
- Utilizzare HTTPS: Per sicurezza, sono supportati solo URL HTTPS
- Restituire stato 2xx: Restituisci un codice di stato di successo per confermare la ricezione
Passo 2: Implementa la Verifica della Firma
GroMach firma tutte le richieste webhook utilizzando HMAC-SHA256. Dovresti verificare questa firma per garantire che le richieste siano autentiche.
Ogni richiesta include questi header:
- x-webhook-signature: Firma HMAC-SHA256 del corpo della richiesta
- x-webhook-timestamp: Timestamp ISO 8601 del momento in cui la richiesta è stata inviata
- Content-Type: application/json
Ecco un esempio di verifica della firma 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 });
});Passo 3: Formato del Payload Webhook
Quando un articolo viene pubblicato, GroMach invia un payload con la seguente struttura:
{
"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"]
}
]
}
}Riferimento Campi Articolo
- id: Identificatore univoco dell'articolo
- slug: Identificatore compatibile con URL per l'articolo
- title: Titolo dell'articolo
- excerpt: Breve descrizione o sommario
- content_format: "markdown" o "html"
- content: Contenuto completo dell'articolo
- status: Stato di pubblicazione (draft, published, archived)
- published_at: Timestamp di pubblicazione ISO 8601
- author_name: Nome visualizzato dell'autore
- cover_image: URL dell'immagine di copertina (se disponibile)
- meta_title: Titolo SEO per i motori di ricerca
- meta_description: Meta descrizione SEO
- tags: Array di stringhe di tag
Passo 4: Configura in GroMach
Nella pagina integrazioni di GroMach, compila le seguenti informazioni:
- Nome (Facoltativo): Un nome descrittivo per identificare questo webhook
- URL Webhook: L'URL del tuo endpoint HTTPS (es. https://your-site.com/api/webhook)
- Chiave Segreta: Una stringa segreta utilizzata per firmare le richieste (mantienila sicura!)
- Stato di Pubblicazione: Scegli se gli articoli vengono inviati come "published" o "draft"
Importante
Mantieni la tua Chiave Segreta al sicuro e non esporla mai nel codice lato client. Utilizza le variabili d'ambiente per archiviarla in modo sicuro sul tuo server.
Testare il Tuo Webhook
Prima di creare l'integrazione, puoi testare la connessione del tuo webhook utilizzando il pulsante "Test Connection". GroMach invierà una richiesta di test per verificare che il tuo endpoint sia configurato correttamente.
Requisiti del Test
Perché il test abbia successo, il tuo endpoint deve:
- 1. Verificare la firma: Utilizza la chiave segreta per verificare l'header
X-Webhook-Signature - 2. Restituire una risposta di successo: Restituisci una risposta JSON con
{ "success": true }
Il payload di test ha questo aspetto:
{
"event_type": "test",
"timestamp": "2024-01-15T10:30:00.000Z",
"data": {
"message": "This is a test webhook from Gromach SEO",
"integration_name": "My Webhook"
}
}Ecco un esempio completo di come il tuo endpoint di test dovrebbe gestire la richiesta:
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 });
});Perché è richiesta la verifica della firma
La verifica della firma garantisce che le richieste webhook provengano effettivamente da GroMach e non siano state manomesse. Questa è una best practice di sicurezza che protegge il tuo endpoint da richieste non autorizzate.
Risoluzione dei Problemi
Il test di connessione fallisce
- • Verifica che l'URL del tuo endpoint sia corretto e utilizzi HTTPS
- • Assicurati che il tuo server sia accessibile da internet
- • Controlla che il tuo endpoint restituisca un codice di stato 2xx
La verifica della firma fallisce
- • Assicurati di utilizzare l'esatta Chiave Segreta da GroMach
- • Verifica di hashare il corpo della richiesta raw, non un oggetto parsato
- • Utilizza un confronto timing-safe per prevenire attacchi di timing
Gli articoli non appaiono
- • Controlla i log del tuo server per eventuali errori di elaborazione
- • Verifica che lo stato dell'articolo corrisponda al flusso di lavoro previsto
- • Assicurati che le operazioni sul database vengano completate con successo