Sviluppatori
La tua fattoria emette eventi. Indirizzali a qualsiasi URL desideri.
Ogni azienda agricola alla fine vuole qualcosa che nessun venditore fornisce: un dashboard sul televisore della stalla, un controller per l'irrigazione fatto in casa che reagisce agli avvisi, uno script di reporting della contea, un ponte verso un software di cui non abbiamo mai sentito parlare. La solita risposta è eseguire il polling di un'API su un timer e sperare che tu non abbia perso nulla tra i sondaggi.
La risposta migliore è quella che i sistemi di produzione utilizzano tra loro: quando succede qualcosa, spingilo, firmalo e riprova finché non arriva.
Come funziona realmente
I POST FarmHub firmano JSON su qualsiasi URL HTTPS configurato, ogni volta che si verificano gli eventi che ti interessano.
- Sei tipi di eventi, presentati man mano che si verificano. Raccolto registrato, avviso generato, avviso risolto, azione correttiva risolta, richiamo avviato e rapporto generato. Ogni evento viene inviato al tuo endpoint come JSON con il nome dell'evento in un'intestazione.
- Ogni payload è firmato HMAC-SHA256. FarmHub genera una chiave di firma per la connessione e firma ogni corpo della richiesta, inviando la firma in un'intestazione X-FarmHub-Signature. Ricalcolare l'HMAC sul corpo grezzo e confrontare. Se non corrisponde, non viene da noi.
- Tentativi di consegna con backoff. Se l'endpoint è inattivo o restituisce un errore, FarmHub riprova con il backoff. Ogni consegna contiene un'intestazione ID di consegna univoca in modo che il gestore possa deduplicare i tentativi.
- I payload hanno una versione e tu controlli l'aggiornamento. Quando la forma del payload cambia, la versione viene modificata e le connessioni esistenti rimangono bloccate alla loro versione finché non accetti. La tua integrazione non si interrompe perché abbiamo inviato un campo.
È lo stesso meccanismo di consegna dietro le nostre integrazioni Slack, Teams e PagerDuty, con la destinazione consegnata a te.
SU COSA PUOI CONTARE
Su cosa puoi contare
Le garanzie, precisamente:
- FarmHub genera la chiave di firma. La chiave HMAC viene creata al momento della connessione e archiviata crittografata durante la connessione. Non esiste un segreto globale condiviso e la rotazione della chiave di una connessione influisce solo su quella connessione.
- Intestazioni create per veri gestori. Ogni richiesta contiene la firma, il nome dell'evento e un ID di consegna univoco, in modo da poter verificare, instradare e deduplicare senza prima analizzare il corpo.
- Interruttore di sicurezza. Disabilita immediatamente la connessione e le consegne si interrompono. Utile quando il tuo endpoint si comporta in modo anomalo o stai ruotando l'infrastruttura.
- Righe di controllo concatenate tramite hash. Ogni tentativo di consegna viene registrato in un registro di controllo le cui righe sono concatenate in modo hash, quindi la cronologia di ciò che è stato inviato e dove è a prova di manomissione.
Cosa non facciamo
I confini onesti:
- La consegna avviene almeno una volta, non esattamente una volta. I nuovi tentativi indicano che il tuo gestore potrebbe vedere una consegna due volte. Deduplica sull'ID di consegna.
- I webhook sono solo in uscita. Questa integrazione non accetta dati in entrata; dice ai tuoi sistemi cosa è successo in FarmHub.
- I sei tipi di eventi sopra riportati sono quelli forniti oggi. Preferiremmo elencare sei eventi reali piuttosto che promettere un catalogo che non abbiamo costruito.
Configurazione, onestamente
È necessario un endpoint HTTPS in grado di ricevere un POST JSON.
- In FarmHub, apri Integrazioni, scegli Webhook personalizzato e inserisci l'URL dell'endpoint. FarmHub genera la chiave di firma HMAC.
- Nel tuo gestore, verifica l'intestazione X-FarmHub-Signature ricalcolando HMAC-SHA256 sul corpo della richiesta non elaborata con la chiave di firma.
- Rispondi velocemente con un 2xx; eseguire un'elaborazione asincrona pesante. Le risposte non 2xx vengono ritentate con backoff.
- Attiva una consegna di prova e conferma che la verifica della firma passa prima di fare affidamento sul feed.
Domande che fanno gli agricoltori
Come posso verificare che un webhook provenga da FarmHub?
Calcola HMAC-SHA256 sul corpo della richiesta non elaborata utilizzando la chiave di firma della connessione e confrontalo con l'intestazione X-FarmHub-Signature, che porta il digest esadecimale con il prefisso sha256=. Rifiuta tutto ciò che non corrisponde.
A quali eventi posso iscrivermi?
Raccolto registrato, avviso generato, avviso risolto, azione correttiva risolta, richiamo avviato e rapporto generato. Il nome dell'evento arriva nell'intestazione X-FarmHub-Event.
Cosa succede se il mio endpoint non funziona?
FarmHub ritenta la consegna con backoff. Poiché la consegna avviene almeno una volta, il gestore deve eseguire la deduplicazione utilizzando l'intestazione ID X-FarmHub-Delivery.
Le modifiche al carico utile interromperanno la mia integrazione?
No. I payload hanno una versione e la tua connessione rimane bloccata alla versione del payload finché non attivi quella nuova.
Posso ruotare la chiave di firma?
Ogni connessione ha la propria chiave generata da FarmHub archiviata crittografata. La riconnessione rilascia una nuova chiave e il kill switch interrompe immediatamente le consegne mentre ruoti.
PRONTO PER IL PROSSIMO TURNO
Costruisci ciò a cui non avevamo pensato
Punta il flusso di eventi firmato di FarmHub sul tuo endpoint e collega la farm a qualsiasi cosa tu possa immaginare: il dashboard del fienile, il controller, il bot di report. Non hai bisogno della nostra autorizzazione, solo di un URL.
Inizia gratuitamente