Trigger: Webhook (`webhook_trigger`)¶

Este trigger inicia una automatización cuando un sistema externo realiza una llamada HTTP a una URL generada por la plataforma. Es ideal para integraciones con servicios de terceros, scripts, o cualquier sistema que pueda enviar peticiones HTTP.

¿Cuándo usarlo?¶

Cuando un servicio externo (GitHub, Stripe, un script propio, etc.) necesita disparar una automatización enviando una petición HTTP.
Cuando querés recibir datos de un sistema de terceros y procesarlos en un flujo.
Cuando necesitás una URL pública que actúe como punto de entrada a una automatización.

Si lo que necesitás es reaccionar a eventos internos del sistema, usá Trigger: Event.
Si lo que necesitás es un disparo manual para pruebas, usá el trigger "When clicked in Test Automation".

Cómo configurarlo (recomendado: usando el formulario)¶

La mayoría de usuarios debería usar la pestaña Form. Es la forma más segura y evita errores de formato.

Paso 0) Abrir la parametrización¶

En el canvas de automatizaciones, hacé doble click sobre el nodo Webhook.
Se abre un modal con dos pestañas: Form y JSON Editor. Quedate en Form.

Paso 1) Definir el Webhook Key¶

El Webhook Key es el identificador único de este webhook. Define la URL que vas a compartir con el sistema externo.

Escribí un nombre descriptivo: por ejemplo alertas-incendio, pagos-stripe, o sensor-puerta-principal.
Solo se permiten: letras (a-z, A-Z), números (0-9), guiones (-) y guiones bajos (_).
No uses espacios ni caracteres especiales.

Una vez que escribís el key, aparece automáticamente la URL generada debajo del campo.

La URL generada¶

Cuando el Webhook Key es válido, la plataforma muestra la URL completa que debés usar:

https://tu-instancia.netsocs.com/api/netsocs/automation/webhooks/mi-webhook-key

Hay un botón de copiar ( icono de copia ) al lado derecho de la URL.
Esta es la URL que tenés que configurar en el sistema externo como destino del webhook.

Paso 2) Elegir los métodos HTTP permitidos¶

El campo Allowed Methods define qué verbos HTTP puede usar el sistema externo para llamar a este webhook.

Método	Cuándo usarlo
`POST`	El más común para webhooks (envío de datos)
`GET`	Para disparos simples sin cuerpo de petición
`PUT`	Para actualizaciones de recursos
`PATCH`	Para modificaciones parciales
`DELETE`	Para notificaciones de eliminación

El método por defecto es POST.
Podés seleccionar más de un método al mismo tiempo (el campo es multi-selección).
Si el sistema externo llama con un método no permitido, el webhook no disparará la automatización.

Paso 3) Configurar la autenticación (recomendado)¶

La sección Authentication define cómo valida el sistema que la llamada viene de un origen legítimo. Hay cuatro opciones:

Opción A — None (sin autenticación)¶

La URL acepta cualquier llamada sin validar identidad.
Solo recomendado para pruebas o redes completamente cerradas.
En producción, cualquier persona que conozca la URL puede disparar la automatización.

Opción B — Header (cabecera personalizada)¶

Verifica que la petición incluya un header HTTP específico con un valor secreto.

Campo	Descripción	Ejemplo
Header Name	Nombre del header HTTP que se espera recibir	`X-Webhook-Secret`
Header Value	Valor secreto que debe coincidir	`mi-secreto-123`

El sistema externo debe incluir este header en cada petición.
Si el header no está presente o el valor no coincide, el webhook es rechazado.

Opción C — Basic Auth (usuario y contraseña)¶

Verifica las credenciales usando el esquema HTTP Basic Auth.

Usá el selector de credenciales para elegir o crear una credencial de tipo basic_auth.
Si ya existe una credencial: seleccionála de la lista.
Si no existe: elegí Create new credential y cargá usuario y contraseña.
Las credenciales se almacenan de forma segura y son reutilizables entre nodos.

Opción D — JWT (JSON Web Token)¶

Verifica que el llamado incluya un token JWT firmado con el secreto compartido.

Campo	Descripción	Opciones disponibles
JWT Secret	Secreto compartido para verificar la firma del JWT	Texto libre (contraseña)
JWT Algorithm	Algoritmo de firma usado al crear el JWT	`HS256` (defecto), `HS384`, `HS512`

El sistema externo debe enviar el JWT en el header Authorization: Bearer <token>.
Si el token no puede verificarse con el secreto y algoritmo configurados, el webhook es rechazado.

Buenas prácticas¶

Siempre usá autenticación en producción: al menos Header con un valor secreto largo y aleatorio.
Usá keys descriptivos: pagos-stripe-confirmados es mejor que webhook1.
Restringí los métodos: si el sistema externo solo usa POST, dejá solo POST habilitado.
No expongas la URL sin autenticación en entornos accesibles desde internet.
Usá JWT si el sistema externo ya tiene soporte nativo para firmar tokens.
Usá Basic Auth o Header si querés la opción más simple y segura a la vez.
Probá antes de activar: enviá una petición de prueba desde el sistema externo y verificá que el flujo se dispara.

Troubleshooting (problemas comunes)¶

El webhook no dispara
Confirmá que el Webhook Key esté guardado y la URL que usa el sistema externo coincida exactamente.
Verificá que el método HTTP que usa el sistema externo esté en la lista de "Allowed Methods".
Si hay autenticación configurada, asegurate de que el sistema externo está enviando las credenciales correctas.
Probá temporalmente con Auth Type = None para descartar problemas de autenticación.
El webhook devuelve error 401 o 403
La autenticación falló. Revisá que el header, usuario/contraseña, o JWT coincidan con lo configurado.
Para Header: verificá nombre y valor exacto (es sensible a mayúsculas).
Para Basic Auth: comprobá que la credencial seleccionada tenga los datos correctos.
Para JWT: verificá que el algoritmo del token generado coincida con el configurado (HS256, HS384, HS512).
El webhook devuelve error 405 Method Not Allowed
El sistema externo está usando un método HTTP que no está habilitado.
Agregá el método correspondiente en Allowed Methods.
No veo la URL generada
La URL solo aparece cuando el campo Webhook Key tiene un valor válido (sin espacios ni caracteres especiales).
Quiero cambiar el Webhook Key sin perder la configuración
Podés cambiar el key desde el formulario. Tené en cuenta que el sistema externo deberá actualizar su URL con el nuevo key.

Configuración avanzada (JSON Editor) (solo usuarios expertos)¶

La pestaña JSON Editor te permite ver y editar directamente la estructura que guarda el nodo. Es útil para:

Copiar configuraciones entre flujos.
Pegar configuraciones desde otra instancia.
Revisar el estado exacto del nodo.

Estructura del `input`¶

{
  "ruleSet": {
    "webhook_key": "mi-webhook-key",
    "allowed_methods": ["POST"],
    "auth": null
  },
  "config": {}
}

Campo	Tipo	Descripción
`ruleSet.webhook_key`	`string`	Identificador único del webhook. Solo `a-z`, `A-Z`, `0-9`, `-`, `_`
`ruleSet.allowed_methods`	`string[]`	Lista de métodos HTTP permitidos
`ruleSet.auth`	`object \\| null`	Configuración de autenticación (`null` = sin autenticación)
`config`	`object`	Siempre `{}` (reservado para uso futuro)

Ejemplos JSON por tipo de autenticación¶

Sin autenticación (solo para pruebas)¶

{
  "ruleSet": {
    "webhook_key": "test-webhook",
    "allowed_methods": ["POST"],
    "auth": null
  },
  "config": {}
}

Autenticación por Header¶

{
  "ruleSet": {
    "webhook_key": "alertas-incendio",
    "allowed_methods": ["POST"],
    "auth": {
      "type": "header",
      "header_name": "X-Webhook-Secret",
      "header_value": "mi-secreto-muy-largo-y-aleatorio"
    }
  },
  "config": {}
}

Autenticación Basic Auth (con referencia a credencial)¶

{
  "ruleSet": {
    "webhook_key": "pagos-stripe",
    "allowed_methods": ["POST"],
    "auth": {
      "type": "basic",
      "username": "/**$credential(\"username\", 42)**/",
      "password": "/**$credential(\"password\", 42)**/"
    }
  },
  "config": {}
}

Los valores de username y password son referencias a credenciales almacenadas de forma segura. El número 42 es el ID de la credencial. No pegues el usuario/contraseña en texto plano directamente en el JSON.

Autenticación JWT¶

{
  "ruleSet": {
    "webhook_key": "sensor-puerta-principal",
    "allowed_methods": ["POST", "GET"],
    "auth": {
      "type": "jwt",
      "jwt_secret": "mi-secreto-compartido",
      "jwt_algorithm": "HS256"
    }
  },
  "config": {}
}

Cómo llama el sistema externo según el tipo de auth¶

POST /api/netsocs/automation/webhooks/alertas-incendio HTTP/1.1
Host: tu-instancia.netsocs.com
Content-Type: application/json
X-Webhook-Secret: mi-secreto-muy-largo-y-aleatorio

{ "sensor": "zona-3", "nivel": "critico" }

Basic Auth¶

POST /api/netsocs/automation/webhooks/pagos-stripe HTTP/1.1
Host: tu-instancia.netsocs.com
Authorization: Basic dXN1YXJpbzpjb250cmFzZW5hCg==
Content-Type: application/json

{ "event": "payment.succeeded", "amount": 1500 }

JWT¶

POST /api/netsocs/automation/webhooks/sensor-puerta-principal HTTP/1.1
Host: tu-instancia.netsocs.com
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...
Content-Type: application/json

{ "door_id": "puerta-norte", "status": "open" }

Guías rápidas (recetas)¶

Receta A — "Cuando Stripe confirma un pago, disparar una acción"¶

Webhook Key: pagos-stripe
Allowed Methods: POST
Auth: Header con el header Stripe-Signature y tu webhook secret de Stripe
Acción: enviar email / crear registro / actualizar estado

Receta B — "Script interno que avisa cuando un archivo es procesado"¶

Webhook Key: archivo-procesado
Allowed Methods: POST
Auth: JWT (el script firma el token con el secreto compartido)
Acción: notificación Telegram / log de auditoría

Receta C — "Sistema de alarma externo que dispara una automatización"¶

Webhook Key: alarma-exterior
Allowed Methods: GET, POST
Auth: Header con X-Alarm-Token
Acción: activar sirena / enviar SMS / cambiar estado de objeto

Receta D — "Prueba rápida desde el navegador o Postman"¶

Webhook Key: prueba-dev
Allowed Methods: GET, POST
Auth: None (solo en entorno de desarrollo)
Acción: log / notificación interna
Una vez validado, configurá autenticación antes de promover a producción

Referencias internas (para ubicarlo en el editor)¶

Key del nodo: webhook_trigger
Clase: trigger
Campos requeridos: webhook_key (obligatorio), allowed_methods (defecto: ["POST"])
Autenticación soportada: none, header, basic, jwt
URL del endpoint: {origin}/api/netsocs/automation/webhooks/{webhook_key}

Trigger: Webhook (webhook_trigger)¶