Desarrolladores
Tu granja emite eventos. Apuntelos a cualquier URL que desee.
Eventualmente, todas las granjas quieren algo que ningún proveedor ofrece: un tablero en el televisor del granero, un controlador de riego de cosecha propia que reacciona a las alertas, un script para informes del condado, un puente hacia un software del que nunca hemos oído hablar. La respuesta habitual es sondear una API con un temporizador y esperar que no te pierdas nada entre las encuestas.
La mejor respuesta es la que los sistemas de producción usan entre sí: cuando sucede algo, empújalo, fírmalo y vuelve a intentarlo hasta que llegue.
Cómo funciona realmente
Los POST de FarmHub firmaron JSON en cualquier URL HTTPS que configure, siempre que ocurran los eventos que le interesan.
- Seis tipos de eventos, impulsados a medida que ocurren. Cosecha registrada, alerta generada, alerta resuelta, acción correctiva resuelta, retirada iniciada y informe generado. Cada evento se envía a su punto final como JSON con el nombre del evento en un encabezado.
- Cada carga útil está firmada por HMAC-SHA256. FarmHub genera una clave de firma para la conexión y firma cada cuerpo de solicitud, enviando la firma en un encabezado X-FarmHub-Signature. Vuelva a calcular el HMAC sobre el cuerpo sin procesar y compare. Si no coincide, no es nuestro.
- Reintentos de entrega con retroceso. Si su punto final no funciona o devuelve un error, FarmHub vuelve a intentarlo con retroceso. Cada entrega lleva un encabezado de identificación de entrega único para que su administrador pueda eliminar los reintentos.
- Las cargas útiles tienen versiones y usted controla la actualización. Cuando la forma de la carga útil cambia, la versión cambia y las conexiones existentes permanecen fijadas a su versión hasta que usted opte por participar. Su integración no se interrumpe porque enviamos un campo.
Es la misma maquinaria de entrega detrás de nuestras integraciones de Slack, Teams y PagerDuty, con el destino entregado a usted.
EN QUÉ PUEDES CONTAR
En qué puedes contar
Las garantías, precisamente:
- FarmHub genera la clave de firma. La clave HMAC se crea en el momento de la conexión y se almacena cifrada en la conexión. No existe un secreto global compartido y la rotación de la clave de una conexión afecta solo a esa conexión.
- Encabezados creados para controladores reales. Cada solicitud lleva la firma, el nombre del evento y una identificación de entrega única, por lo que puede verificar, enrutar y deduplicar sin analizar primero el cuerpo.
- Interruptor de apagado. Desactiva la conexión al instante y las entregas se detienen. Útil cuando su terminal no funciona correctamente o está rotando la infraestructura.
- Filas de auditoría encadenadas mediante hash. Cada intento de entrega se registra en un registro de auditoría cuyas filas están encadenadas mediante hash, por lo que el historial de lo que se envió es a prueba de manipulaciones.
Lo que no hacemos
Los límites honestos:
- La entrega se realiza al menos una vez, no exactamente una vez. Los reintentos significan que su controlador puede ver una entrega dos veces. Deduplicar en la identificación de entrega.
- Los webhooks son únicamente salientes. Esta integración no acepta datos entrantes; le dice a sus sistemas lo que sucedió en FarmHub.
- Los seis tipos de eventos anteriores son los que se envían hoy. Preferimos enumerar seis eventos reales que prometer un catálogo que no hemos creado.
Configuración, honestamente
Necesita un punto final HTTPS que pueda recibir un JSON POST.
- En FarmHub, abra Integraciones, elija Webhook personalizado e ingrese la URL de su punto final. FarmHub genera la clave de firma HMAC.
- En su controlador, verifique el encabezado X-FarmHub-Signature recalculando HMAC-SHA256 sobre el cuerpo de la solicitud sin procesar con la clave de firma.
- Responde con un 2xx rápidamente; realizar un procesamiento pesado asíncrono. Las respuestas que no sean 2xx se reintentan con retroceso.
- Active una entrega de prueba y confirme sus pases de verificación de firma antes de confiar en el feed.
Preguntas que hacen los agricultores
¿Cómo verifico que un webhook proviene de FarmHub?
Calcule HMAC-SHA256 sobre el cuerpo de la solicitud sin formato utilizando la clave de firma de la conexión y compárelo con el encabezado X-FarmHub-Signature, que lleva el resumen hexadecimal con el prefijo sha256=. Rechaza todo lo que no coincida.
¿A qué eventos puedo suscribirme?
Cosecha registrada, alerta generada, alerta resuelta, acción correctiva resuelta, retirada iniciada y informe generado. El nombre del evento llega al encabezado X-FarmHub-Event.
¿Qué sucede si mi terminal no funciona?
FarmHub reintenta la entrega con retroceso. Debido a que la entrega se realiza al menos una vez, su controlador debe deduplicar utilizando el encabezado de identificación X-FarmHub-Delivery.
¿Los cambios en la carga útil interrumpirán mi integración?
No. Las cargas útiles tienen versiones y su conexión permanece fijada a su versión de carga útil hasta que opte por la nueva.
¿Puedo rotar la clave de firma?
Cada conexión tiene su propia clave generada por FarmHub almacenada encriptada. La reconexión emite una clave nueva y el interruptor de apagado detiene las entregas instantáneamente mientras gira.
LISTO PARA EL PRÓXIMO TURNO
Construir lo que no pensamos
Dirija el flujo de eventos firmado de FarmHub a su propio punto final y conecte la granja a lo que pueda imaginar: el panel del granero, el controlador, el robot de informes. No necesitas nuestro permiso, solo una URL.
Empieza gratis