Si tienes tu propio sistema (un CRM, un panel interno o un bot), los webhooks de SemSerp te envían los cambios de posición en cuanto se calculan, sin que tengas que preguntar. Es la forma más directa de llevar los cambios del rank tracker de SemSerp a tus sistemas.
En resumen
- Cada mañana con cambios recibes un POST con JSON (evento daily_summary).
- Cada envío va firmado con HMAC-SHA256 en la cabecera X-SemSerp-Signature.
- Solo se aceptan URLs https públicas.
- Disponible desde el plan Pro.
Qué recibes
Un POST con Content-Type: application/json y estas cabeceras:
| Cabecera | Contenido |
|---|---|
| X-SemSerp-Event | El tipo de evento: daily_summary o test |
| X-SemSerp-Signature | sha256= seguido del HMAC-SHA256 del cuerpo con tu secreto |
| User-Agent | SemSerp-Webhooks/1.0 |
Ejemplo de cuerpo:
{
"event": "daily_summary",
"date": "2026-11-20",
"device": "mobile",
"project": {
"id": "abc123",
"name": "Mi tienda",
"domain": "tuweb.com"
},
"up": [
{
"keyword": "zapatillas trail",
"before": 8,
"now": 4
}
],
"down": [],
"entered_top3": [],
"left_top3": [],
"entered_top10": [
"zapatillas running mujer"
],
"left_top10": [],
"counts": {
"up": 1,
"down": 0,
"entered_top3": 0,
"left_top3": 0,
"entered_top10": 1,
"left_top10": 0
},
"id": "2026-11-20-abc123-daily_summary",
"url": "https://…/#/p/abc123"
}
Antes de empezar
| Requisito | Detalle |
|---|---|
| Plan | Pro o superior |
| Endpoint | Una URL https pública que acepte POST y responda 2xx |
| Tiempo | De 10 a 30 minutos, según tu sistema |
Paso a paso
- En Integraciones, en la tarjeta Webhooks, pega tu URL.
- Elige todos tus proyectos o uno concreto y pulsa Añadir.
- Guarda el secreto que aparece: solo se enseña una vez.
- Pulsa Enviar prueba: recibirás un evento
test.

Comprueba la firma
Antes de fiarte del mensaje, calcula el HMAC-SHA256 del cuerpo en bruto con tu secreto y compáralo con la cabecera:
// Node.js: comprobar la firma del webhook de SemSerp
const crypto = require("crypto");
function firmaValida(cuerpoEnBruto, cabecera, secreto) {
const esperada = "sha256=" + crypto.createHmac("sha256", secreto).update(cuerpoEnBruto).digest("hex");
return cabecera.length === esperada.length &&
crypto.timingSafeEqual(Buffer.from(cabecera), Buffer.from(esperada));
}
Importante
- Calcula la firma sobre el cuerpo en bruto, antes de convertirlo a JSON.
- Usa el campo
idpara no procesar dos veces el mismo envío. - Responde rápido con un 2xx y procesa en segundo plano si tu lógica es lenta.
Ideas de uso
- Crear una tarea en tu gestor cuando una keyword importante sale del Top 3.
- Guardar el histórico diario en tu propia base de datos o en BigQuery.
- Avisar en tu propio bot o app interna.
- Si prefieres consultar en lugar de recibir, usa la API de lectura.
Errores frecuentes y cómo resolverlos
| Problema | Causa probable | Solución |
|---|---|---|
| No llega nada | La URL no es pública o no es https | Usa una URL https accesible desde internet |
| La firma no coincide | Se calcula sobre el JSON ya interpretado | Calcúlala sobre el cuerpo en bruto, tal cual llega |
| El destino aparece pausado | Varios envíos seguidos fallaron | Corrige el endpoint y pulsa «Enviar prueba» para reactivarlo |
| He perdido el secreto | Solo se muestra una vez | Borra el destino y créalo de nuevo |
Buenas prácticas
- Guarda el secreto en un gestor de secretos, nunca en el código.
- Registra los envíos recibidos con su id para poder depurar.
- Empieza con un endpoint de prueba y pasa a producción cuando la firma valide.
Preguntas frecuentes
¿Qué pasa si mi servidor falla?
Si los envíos fallan varias veces seguidas, el destino se pausa. Cuando lo arregles, envía una prueba para reactivarlo.
¿Puedo usar una URL interna o de mi red local?
No. Por seguridad solo se aceptan URLs https públicas.
¿Cada cuánto se envía?
Una vez al día, por la mañana, cuando hay cambios. El evento de prueba se envía cuando pulsas «Enviar prueba».
¿Desde qué plan está?
Desde el plan Pro.
¿Puedo filtrar qué proyectos envía el webhook?
Sí. Al añadir el destino eliges todos tus proyectos o uno concreto, y puedes crear varios destinos con proyectos distintos.
Te puede interesar
Pruébalo con tu web
Crea tu cuenta y conecta tus posiciones con tu propio sistema.
Empieza gratisVer planes