Integraciones y API
Un webhook envía automáticamente datos a un sistema externo en cuanto ocurre un evento (una medición nueva, una alerta, una desconexión…). Puede enviarlos por HTTP, a una URL de tu sistema, o publicarlos por MQTT en tu propio broker. Se configuran en Organización › Integraciones, pestaña Envío de datos.
Crear un webhook
Pulsa + Crear webhook. El asistente tiene tres pasos:
1. Información del webhook
Ponle un nombre y una descripción. Solo sirven para identificarlo.
2. Dispositivos y eventos
•
Marca uno o varios dispositivos en el selector (puedes buscar por red o por nombre y elegir varios de una vez).
•
Marca los eventos que lo dispararán: Nueva medición, Alertas - Alarmas, Dispositivo desconectado o Batería baja.
Si en el selector aparece — no reenvía (no está en el LNS) junto al nombre de un dispositivo, el webhook no recibirá nada de él, sea cual sea el método. El envío lo hace la nube al decodificar cada transmisión, y ese dispositivo no pasa por ahí: ni se conecta a través del servidor de red LoRaWAN (LNS) de la nube ni tiene SIM propia.
3. Configurar la conexión
•
URL de destino (el endpoint que recibirá los datos, o el broker si eliges MQTT).
•
Método de solicitud: POST, PUT o MQTT.
Con POST o PUT, la URL tiene que empezar por
http:// o https://, y puedes añadir, opcionalmente, hasta 5 de cada uno de estos parámetros:•
Encabezados: se envían tal cual en la petición (úsalos para autenticación, por ejemplo
Authorization).•
Query parameters: se añaden a la URL de destino.
•
Body parameters: se añaden al cuerpo (JSON) junto con los datos del sensor.
Ninguna clave o valor puede quedar vacío: si dejas un parámetro incompleto, el formulario lo marcará y no dejará guardar.
Con MQTT el formulario cambia: lo explica el apartado «Enviar datos por MQTT», más abajo.
Pulsa Crear webhook. Verás la confirmación y el webhook aparecerá en la lista.
Ten en cuenta
Con POST o PUT, para autenticarte contra tu sistema añade la credencial como encabezado (por ejemplo,
Authorization): el webhook no tiene un campo de autenticación aparte. Cada envío se hará con el método y los parámetros que hayas configurado.Enviar datos por MQTT
Con el método MQTT, Nescloud publica los datos de tus dispositivos en tu propio broker MQTT en lugar de hacer una petición HTTP. Al elegir MQTT en Método de solicitud desaparecen Encabezados, Query parameters y Body parameters, que no se usan con MQTT, y aparecen los campos de acceso al broker.
La URL del broker y el topic
En URL de destino, escribe la dirección del broker seguida del topic en el que quieres publicar:
•
mqtt://host:puerto/topic, para una conexión sin cifrar.•
mqtts://host:puerto/topic, para una conexión cifrada con TLS.Por ejemplo:
mqtt://broker.example.com:1883/Nespra/{deveui}.•
Si no indicas el puerto, se usa el 1883 con
mqtt:// y el 8883 con mqtts://.•
Escribe
{deveui} en el topic y se sustituirá por el DevEUI de cada dispositivo (por ejemplo, Nespra/24-e1-24-13-6d-22-73-34). Si no lo escribes, el DevEUI irá dentro de cada mensaje.•
El topic no puede llevar los caracteres
+, # ni ?.•
El usuario y la contraseña no van dentro de la URL, sino en sus propios campos.
•
El broker tiene que ser accesible desde internet: no se admiten direcciones privadas o internas.
•
Con
mqtts://, el certificado del broker tiene que ser válido y estar emitido por una autoridad de certificación reconocida. Con un certificado autofirmado, la conexión fallará.Usuario y contraseña del broker
Rellena Usuario del broker y Contraseña del broker con los datos de acceso a tu broker (100 caracteres como máximo cada uno). Si tu broker no pide autenticación, deja los dos vacíos; si indicas el usuario, la contraseña es obligatoria.
La contraseña guardada no vuelve a mostrarse. Al editar el webhook, el campo aparece vacío con el texto «Guardada. Déjala vacía para conservarla»: déjalo así para mantenerla o escribe una nueva para cambiarla.
Atención
Nescloud no se conecta a tu broker al guardar: solo comprueba que la URL y los datos de acceso tienen un formato correcto. Si el usuario o la contraseña son incorrectos, el webhook se guardará igualmente y los datos no llegarán.
Qué se publica
Cada vez que un dispositivo del webhook envía datos, Nescloud publica cada métrica por separado, en su propio subtopic (
<topic>/<métrica>) y con este contenido:•
value: el valor tal como lo decodifica el dispositivo, sin unidad.•
TimeStamp: la hora de la lectura, en segundos UTC desde el 1 de enero de 1970 (tiempo Unix).•
deveui: el DevEUI del dispositivo, solo si el topic no lleva {deveui}.Por ejemplo, con el topic
Nespra/{deveui}, una lectura de temperatura y humedad publica dos mensajes:| Topic | Mensaje |
|---|---|
Nespra/24-e1-24-13-6d-22-73-34/temperature | {"value": 28.7, "TimeStamp": 1790924939} |
Nespra/24-e1-24-13-6d-22-73-34/humidity | {"value": 53, "TimeStamp": 1790924939} |
Ten en cuenta además que:
•
Si una transmisión trae varias lecturas guardadas de momentos distintos, cada una se publica con su propia hora.
•
Las transmisiones sin datos de medida (por ejemplo, cuando el dispositivo se une a la red) no publican nada.
•
Los mensajes se publican con QoS 0 y sin retener. Nescloud abre una conexión nueva con el broker en cada envío, con un identificador de cliente que empieza por
NesAPI_.Comprobar que llegan los datos
El botón Probar webhook no está disponible para los webhooks MQTT: aparece deshabilitado. Para comprobar que funciona, suscríbete en tu broker al topic del webhook (por ejemplo,
Nespra/#) y espera a la siguiente transmisión de uno de sus dispositivos.Si vienes del modo Híbrido de la red
Si hasta ahora recibías los datos en tu broker con el modo Híbrido de la red, en el que el propio Nesgate los reenviaba, el webhook MQTT hace lo mismo desde la nube y con el mismo formato de mensaje. Cambian tres cosas:
•
Las conexiones a tu broker ya no llegan desde tus Nesgates, sino desde la nube de Nescloud. Si tu broker solo acepta conexiones desde direcciones IP conocidas, pide a soporte la dirección que tienes que permitir.
•
El Nesgate reenviaba cualquier Nesmote que oyera. El webhook solo envía los dispositivos que hayas marcado: cuando des de alta uno nuevo, edita el webhook y añádelo.
•
El nombre de algunas métricas puede cambiar, porque ahora lo pone el decodificador de la nube (por ejemplo,
battery en lugar de vdd). Comprueba que tu sistema los reconoce antes de hacer el cambio.Probar un webhook
Una vez creado, puedes comprobar que funciona sin esperar a que llegue un dato real. En la lista de webhooks, pulsa el botón Probar webhook (icono de envío) de la fila. La prueba solo está disponible para los webhooks POST y PUT.
Nescloud envía una petición de prueba real a la URL configurada y muestra el resultado:
•
El código de estado y el tiempo de respuesta.
•
Los encabezados y el cuerpo que se han enviado.
•
La respuesta que devuelve tu sistema.
El cuerpo de prueba usa las métricas reales de los sensores del dispositivo, pero con valores de ejemplo. Si el webhook tiene varios dispositivos, se envía una petición por cada tipo de dispositivo, igual que en producción (donde cada dispositivo manda su propio dato, nunca todas las métricas juntas). Los dispositivos con la misma estructura se agrupan y se prueban como máximo 5 estructuras distintas.
Ten en cuenta
La prueba usa la misma configuración que el envío real (método, URL, encabezados, query y body parameters), así que sirve para validar de extremo a extremo la conexión y la autenticación.
Atención
La URL de destino debe ser una dirección pública accesible por internet (http o https). No se permite probar contra direcciones privadas o internas.
Si no se puede guardar el webhook
Al pulsar Crear webhook (el botón se llama igual cuando editas uno existente), Nescloud comprueba el método, la URL y, con MQTT, los datos de acceso al broker. Si algo no es correcto, el motivo aparece en la propia ventana, que se queda abierta para que lo corrijas:
| Mensaje | Qué hacer |
|---|---|
| Indica la URL de destino. | Rellena URL de destino. |
| La URL de destino no puede tener más de 200 caracteres. | Acorta la URL o, con MQTT, el topic. |
| La URL de destino tiene que empezar por http:// o https://. | Con POST o PUT, escribe la URL completa, con http:// o https://. |
| El método no es válido. | Vuelve a elegir el método en Método de solicitud. |
| La URL del broker tiene que ser mqtt://host:puerto/topic o mqtts://host:puerto/topic, sin usuario ni contraseña dentro. | Revisa el formato de la URL y quita el usuario o la contraseña si los has puesto en ella. |
| Falta el topic, o lleva caracteres no permitidos (+, # o ?). | Añade el topic después del host y el puerto, sin esos caracteres. |
| El broker apunta a una dirección privada o interna y no está permitido. | Usa la dirección pública del broker. |
| Indica la contraseña del broker. | Has escrito el usuario: añade también la contraseña. |
| Indica el usuario del broker junto con la contraseña. | Has escrito la contraseña: añade también el usuario. |
| El usuario y la contraseña del broker no pueden tener más de 100 caracteres. | Acórtalos. |
| No se ha podido guardar el webhook. | Vuelve a intentarlo y, si se repite, contacta con soporte. |
Manual de usuario de Nescloud · Integraciones y API. Si necesitas ayuda con un caso concreto, contacta con el soporte de tu organización.