Aperçu
L'intégration Webhook vous permet de recevoir les données d'articles de GroMach et de les traiter dans votre propre système backend. Lorsque vous publiez un article, GroMach envoie une requête POST à votre endpoint configuré avec le contenu de l'article.
Étape 1 : Configurer votre endpoint Webhook
Créez un endpoint HTTPS sur votre serveur pour recevoir les requêtes webhook. L'endpoint doit :
- Accepter les requêtes POST : Toutes les données webhook sont envoyées via POST
- Utiliser HTTPS : Pour la sécurité, seules les URL HTTPS sont supportées
- Retourner un statut 2xx : Retournez un code de statut de succès pour confirmer la réception
Étape 2 : Implémenter la vérification de signature
GroMach signe toutes les requêtes webhook en utilisant HMAC-SHA256. Vous devez vérifier cette signature pour vous assurer que les requêtes sont authentiques.
Chaque requête inclut ces en-têtes :
- x-webhook-signature : Signature HMAC-SHA256 du corps de la requête
- x-webhook-timestamp : Horodatage ISO 8601 de l'envoi de la requête
- Content-Type : application/json
Voici un exemple de vérification de signature en 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 });
});Étape 3 : Format du payload Webhook
Lorsqu'un article est publié, GroMach envoie un payload avec la structure suivante :
{
"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"]
}
]
}
}Référence des champs d'article
- id : Identifiant unique de l'article
- slug : Identifiant compatible URL pour l'article
- title : Titre de l'article
- excerpt : Brève description ou résumé
- content_format : Soit "markdown" soit "html"
- content : Contenu complet de l'article
- status : Statut de publication (draft, published, archived)
- published_at : Horodatage de publication ISO 8601
- author_name : Nom d'affichage de l'auteur
- cover_image : URL de l'image de couverture (si disponible)
- meta_title : Titre SEO pour les moteurs de recherche
- meta_description : Méta-description SEO
- tags : Tableau de chaînes de tags
Étape 4 : Configurer dans GroMach
Dans la page des intégrations GroMach, remplissez les informations suivantes :
- Nom (Optionnel) : Un nom convivial pour identifier ce webhook
- URL du Webhook : L'URL de votre endpoint HTTPS (ex : https://votre-site.com/api/webhook)
- Clé secrète : Une chaîne secrète utilisée pour signer les requêtes (gardez-la sécurisée !)
- Statut de publication : Choisissez si les articles sont envoyés comme "published" ou "draft"
Important
Gardez votre clé secrète en sécurité et ne l'exposez jamais dans le code côté client. Utilisez des variables d'environnement pour la stocker en toute sécurité sur votre serveur.
Tester votre Webhook
Avant de créer l'intégration, vous pouvez tester votre connexion webhook en utilisant le bouton "Tester la connexion". GroMach enverra une requête de test pour vérifier que votre endpoint est correctement configuré.
Exigences du test
Pour que le test réussisse, votre endpoint doit :
- 1. Vérifier la signature : Utilisez la clé secrète pour vérifier l'en-tête
X-Webhook-Signature - 2. Retourner une réponse de succès : Retournez une réponse JSON avec
{ "success": true }
Le payload de test ressemble à ceci :
{
"event_type": "test",
"timestamp": "2024-01-15T10:30:00.000Z",
"data": {
"message": "This is a test webhook from Gromach SEO",
"integration_name": "My Webhook"
}
}Voici un exemple complet de la façon dont votre endpoint de test doit gérer la requête :
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 });
});Pourquoi la vérification de signature est requise
La vérification de signature garantit que les requêtes webhook proviennent bien de GroMach et n'ont pas été altérées. C'est une bonne pratique de sécurité qui protège votre endpoint contre les requêtes non autorisées.
Dépannage
Le test de connexion échoue
- • Vérifiez que l'URL de votre endpoint est correcte et utilise HTTPS
- • Assurez-vous que votre serveur est accessible depuis Internet
- • Vérifiez que votre endpoint retourne un code de statut 2xx
La vérification de signature échoue
- • Assurez-vous d'utiliser la clé secrète exacte de GroMach
- • Vérifiez que vous hachez le corps de requête brut, pas un objet parsé
- • Utilisez une comparaison sécurisée contre les attaques temporelles
Les articles n'apparaissent pas
- • Vérifiez les journaux de votre serveur pour détecter les erreurs de traitement
- • Vérifiez que le statut de l'article correspond à votre workflow attendu
- • Assurez-vous que vos opérations de base de données se terminent avec succès