Descripción General
La integración de Webhook te permite recibir datos de artículos de GroMach y procesarlos en tu propio sistema backend. Cuando publicas un artículo, GroMach envía una solicitud POST a tu endpoint configurado con el contenido del artículo.
Paso 1: Configura tu Endpoint de Webhook
Crea un endpoint HTTPS en tu servidor para recibir solicitudes de webhook. El endpoint debe:
- Aceptar solicitudes POST: Todos los datos del webhook se envían vía POST
- Usar HTTPS: Por seguridad, solo se admiten URLs HTTPS
- Devolver estado 2xx: Devuelve un código de estado exitoso para confirmar la recepción
Paso 2: Implementa la Verificación de Firma
GroMach firma todas las solicitudes de webhook usando HMAC-SHA256. Debes verificar esta firma para asegurar que las solicitudes sean auténticas.
Cada solicitud incluye estos encabezados:
- x-webhook-signature: Firma HMAC-SHA256 del cuerpo de la solicitud
- x-webhook-timestamp: Marca de tiempo ISO 8601 de cuando se envió la solicitud
- Content-Type: application/json
Aquí hay un ejemplo de verificación de firma 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 });
});Paso 3: Formato del Payload del Webhook
Cuando se publica un artículo, GroMach envía un payload con la siguiente estructura:
{
"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"]
}
]
}
}Referencia de Campos del Artículo
- id: Identificador único del artículo
- slug: Identificador amigable para URL del artículo
- title: Título del artículo
- excerpt: Breve descripción o resumen
- content_format: "markdown" o "html"
- content: Contenido completo del artículo
- status: Estado de publicación (draft, published, archived)
- published_at: Marca de tiempo de publicación ISO 8601
- author_name: Nombre de visualización del autor
- cover_image: URL de la imagen de portada (si está disponible)
- meta_title: Título SEO para motores de búsqueda
- meta_description: Meta descripción SEO
- tags: Array de etiquetas en formato string
Paso 4: Configura en GroMach
En la página de integraciones de GroMach, completa la siguiente información:
- Nombre (Opcional): Un nombre descriptivo para identificar este webhook
- URL del Webhook: La URL de tu endpoint HTTPS (ej., https://tu-sitio.com/api/webhook)
- Clave Secreta: Una cadena secreta utilizada para firmar solicitudes (¡mantén esto seguro!)
- Estado de Publicación: Elige si los artículos se envían como "published" o "draft"
Importante
Mantén tu Clave Secreta segura y nunca la expongas en código del lado del cliente. Usa variables de entorno para almacenarla de forma segura en tu servidor.
Prueba tu Webhook
Antes de crear la integración, puedes probar tu conexión de webhook usando el botón "Probar Conexión". GroMach enviará una solicitud de prueba para verificar que tu endpoint esté correctamente configurado.
Requisitos de la Prueba
Para que la prueba sea exitosa, tu endpoint debe:
- 1. Verificar la firma: Usa la clave secreta para verificar el encabezado
X-Webhook-Signature - 2. Devolver respuesta exitosa: Devuelve una respuesta JSON con
{ "success": true }
El payload de prueba se ve así:
{
"event_type": "test",
"timestamp": "2024-01-15T10:30:00.000Z",
"data": {
"message": "This is a test webhook from Gromach SEO",
"integration_name": "My Webhook"
}
}Aquí hay un ejemplo completo de cómo tu endpoint de prueba debería manejar la solicitud:
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 });
});Por qué se requiere la verificación de firma
La verificación de firma asegura que las solicitudes de webhook sean genuinamente de GroMach y no hayan sido alteradas. Esta es una práctica de seguridad recomendada que protege tu endpoint de solicitudes no autorizadas.
Solución de Problemas
La prueba de conexión falla
- • Verifica que la URL de tu endpoint sea correcta y use HTTPS
- • Asegúrate de que tu servidor sea accesible desde internet
- • Comprueba que tu endpoint devuelva un código de estado 2xx
La verificación de firma falla
- • Asegúrate de estar usando la Clave Secreta exacta de GroMach
- • Verifica que estés hasheando el cuerpo de la solicitud sin procesar, no un objeto parseado
- • Usa comparación segura en tiempo para prevenir ataques de tiempo
Los artículos no aparecen
- • Revisa los logs de tu servidor en busca de errores de procesamiento
- • Verifica que el estado del artículo coincida con tu flujo de trabajo esperado
- • Asegúrate de que tus operaciones de base de datos se completen exitosamente