Passer au contenu

Exploitation agricole indépendante / construite pour le prochain quart de travail

Développeurs

Votre ferme émet des événements. Dirigez-les vers n’importe quelle URL de votre choix.

Chaque ferme veut finalement quelque chose qu'aucun fournisseur ne livre : un tableau de bord sur le téléviseur de la grange, un contrôleur d'irrigation développé en interne qui réagit aux alertes, un script de rapport de comté, un pont vers un logiciel dont nous n'avons jamais entendu parler. La réponse habituelle consiste à interroger une API sur une minuterie et à espérer que vous n'avez rien manqué entre les sondages.

La meilleure réponse est celle que les systèmes de production utilisent entre eux : quand quelque chose se produit, poussez-le, signez-le et réessayez jusqu'à ce qu'il atterrisse.

Comment ça marche réellement

FarmHub POST signe JSON sur n'importe quelle URL HTTPS que vous configurez, chaque fois que les événements qui vous intéressent se produisent.

  • Six types d'événements, poussés au fur et à mesure qu'ils se produisent. Récolte enregistrée, alerte déclenchée, alerte résolue, action corrective résolue, rappel lancé et rapport généré. Chaque événement est POST sur votre point de terminaison au format JSON avec le nom de l'événement dans un en-tête.
  • Chaque charge utile est signée HMAC-SHA256. FarmHub génère une clé de signature pour la connexion et signe chaque corps de requête, en envoyant la signature dans un en-tête X-FarmHub-Signature. Recalculez le HMAC sur le corps brut et comparez. Si cela ne correspond pas, cela ne vient pas de nous.
  • Nouvelles tentatives de livraison avec interruption. Si votre point de terminaison est en panne ou renvoie une erreur, FarmHub réessaye avec interruption. Chaque livraison comporte un en-tête d’identifiant de livraison unique afin que votre gestionnaire puisse dédoublonner les tentatives.
  • Les charges utiles sont versionnées et vous contrôlez la mise à niveau. Lorsque la forme de la charge utile change, la version est modifiée et les connexions existantes restent épinglées sur leur version jusqu'à ce que vous vous inscriviez. Votre intégration ne s'interrompt pas car nous avons expédié un champ.

Il s'agit du même mécanisme de livraison derrière nos intégrations Slack, Teams et PagerDuty, avec la destination qui vous est remise.

SUR QUOI VOUS POUVEZ COMPTER

Sur quoi vous pouvez compter

Les garanties, justement :

  • FarmHub génère la clé de signature. La clé HMAC est créée au moment de la connexion et stockée cryptée sur la connexion. Il n’existe pas de secret global partagé et la rotation de la clé d’une connexion affecte uniquement cette connexion.
  • En-têtes conçus pour les vrais gestionnaires. Chaque demande porte la signature, le nom de l'événement et un identifiant de livraison unique, afin que vous puissiez vérifier, acheminer et dédupliquer sans analyser le corps au préalable.
  • Coupe-circuit. Désactivez la connexion instantanément et les livraisons s'arrêtent. Utile lorsque votre point de terminaison se comporte mal ou que vous effectuez une rotation de l'infrastructure.
  • Lignes d'audit chaînées par hachage. Chaque tentative de livraison est enregistrée dans un journal d'audit dont les lignes sont chaînées par hachage, de sorte que l'historique de ce qui a été envoyé et où est inviolable.

Ce que nous ne faisons pas

Les limites honnêtes :

  • La livraison s'effectue au moins une fois, pas exactement une fois. Les nouvelles tentatives signifient que votre gestionnaire peut voir une livraison deux fois. Dédoublonner sur l'identifiant de livraison.
  • Les webhooks sont sortants uniquement. Cette intégration n'accepte pas les données entrantes ; il indique à vos systèmes ce qui s'est passé dans FarmHub.
  • Les six types d'événements ci-dessus sont ceux qui sont disponibles aujourd'hui. Nous préférons lister six événements réels plutôt que de promettre un catalogue que nous n'avons pas construit.

Configuration, honnêtement

Vous avez besoin d'un point de terminaison HTTPS capable de recevoir un POST JSON.

  1. Dans FarmHub, ouvrez Intégrations, choisissez Webhook personnalisé et saisissez l'URL de votre point de terminaison. FarmHub génère la clé de signature HMAC.
  2. Dans votre gestionnaire, vérifiez l'en-tête X-FarmHub-Signature en recalculant HMAC-SHA256 sur le corps brut de la requête avec la clé de signature.
  3. Répondez rapidement avec un 2xx ; effectuer un traitement asynchrone lourd. Les réponses non-2xx sont réessayées avec une interruption.
  4. Déclenchez une livraison test et confirmez la réussite de la vérification de votre signature avant de vous fier au flux.

Questions posées par les agriculteurs

Comment puis-je vérifier qu'un webhook provient de FarmHub ?

Calculez HMAC-SHA256 sur le corps brut de la requête à l'aide de la clé de signature de la connexion et comparez-le à l'en-tête X-FarmHub-Signature, qui contient le résumé hexadécimal préfixé par sha256=. Rejetez tout ce qui ne correspond pas.

À quels événements puis-je m'abonner ?

Récolte enregistrée, alerte déclenchée, alerte résolue, action corrective résolue, rappel lancé et rapport généré. Le nom de l'événement arrive dans l'en-tête X-FarmHub-Event.

Que se passe-t-il si mon point de terminaison est en panne ?

FarmHub tente à nouveau la livraison avec interruption. Étant donné que la livraison s'effectue au moins une fois, votre gestionnaire doit dédupliquer à l'aide de l'en-tête X-FarmHub-Delivery id.

Les modifications de la charge utile interrompront-elles mon intégration ?

Non. Les charges utiles sont versionnées et votre connexion reste épinglée sur sa version de charge utile jusqu'à ce que vous optiez pour la nouvelle.

Puis-je faire pivoter la clé de signature ?

Chaque connexion possède sa propre clé générée par FarmHub et stockée cryptée. La reconnexion génère une nouvelle clé et le kill switch arrête les livraisons instantanément pendant que vous faites la rotation.

PRÊT POUR LE PROCHAIN ​​CHANGEMENT

Construire la chose à laquelle nous n'avions pas pensé

Pointez le flux d'événements signés de FarmHub sur votre propre point de terminaison et connectez la ferme à tout ce que vous pouvez imaginer : le tableau de bord de l'étable, le contrôleur, le robot de rapport. Vous n'avez pas besoin de notre autorisation, juste d'une URL.

Commencez gratuitement