Los vendors que «solo hacen POST JSON» casi nunca dejan reescribir el mensaje. AlertHub sí: campos reservados ah_* más Mustache {{path.to.field}} sobre el resto del payload (objetos anidados, hasta 10 niveles). Puedes poner plantillas en la query string para que Stripe y Shopify no necesiten un servidor en medio.
El constructor de webhooks genera o parsea esas URLs. El contrato es la API de ingestión.
Reservados vs personalizados
| Campo | Rol |
|---|---|
ah_key | Secreto del proyecto (obligatorio) |
ah_title | Plantilla del título (obligatorio) |
ah_description | Plantilla del cuerpo |
ah_level | info | warning | critical (default info) |
ah_source | Etiqueta en el feed |
| Cualquier otro | Variable para {{name}} |
Si la misma clave aparece en la URL y en el JSON, gana el body. Mézclalos: deja ah_key en la query (fácil de rotar en el Admin de Shopify) y envía el evento gordo de Stripe como POST JSON.
Configuración (una sola vez)
- Copia el secreto de app.thealerthub.com.
- Abre el constructor, pega la clave, pon título/origen/nivel/descripción.
- Copia la URL al vendor, o importa una URL existente para ver qué codifica.
Ejemplo 1: Pedido Shopify (plantillas en query)
Shopify hace POST del JSON del pedido a tu URL. Título y descripción en la query apuntan a campos planos:
ah_title=Nueva venta {{name}}
ah_description={{email}} gastó {{total_price}} {{currency}}
Guía: alertas de pedidos Shopify.
Ejemplo 2: Objetos anidados de Stripe
Los eventos Stripe anidan bajo data.object. Usa rutas con puntos:
ah_title=Stripe {{type}}
ah_description=Importe {{data.object.amount}} {{data.object.currency}}
Los widgets de pago fallido están en esa guía. La misma idea en GitHub: {{repository.name}}, {{sender.login}} — webhooks de repo.
Ejemplo 3: JSON completo desde tu app
Cuando controlas el cliente, olvida las plantillas en query y envía:
{
"ah_key": "YOUR_KEY",
"ah_title": "Deploy {{commit.id}}",
"ah_description": "Author {{commit.author}}",
"ah_level": "warning",
"ah_source": "API",
"commit": { "id": "abc1234", "author": "Ada" }
}Título resultante: Deploy abc1234. Arrays: {{line_items.0.title}}.
Ideas para sacarle más partido
- Nunca pongas la clave en un repo público. Prefiere secrets de GitHub Actions o la config de webhooks del vendor.
- Importar URL en el constructor cuando un compañero envía un enlace misterioso.
- El nivel en la query (
ah_level=critical) es cómo UptimeRobot y Vercel paginan sin cambiar código. Niveles.
Preguntas frecuentes
¿Los placeholders corren en n8n antes del POST?
El {{ $json }} de n8n corre primero. El {{data.object.id}} de AlertHub corre en el servidor tras la ingesta. Guía n8n.
¿Y si la ruta no existe?
El placeholder suele quedar vacío. Inspecciona un payload real una vez.
¿GET o POST?
POST JSON es lo preferido. Solo query vale para vendors que no pueden poner body.
Siguientes pasos
Construye una URL en el constructor, pégala en Shopify o Stripe y confirma la interpolación en el panel.
Relacionado: API de ingestión · enviar desde Node, Python y PHP