Pular para o conteúdo

Operações agrícolas independentes / construídas para o próximo turno

Desenvolvedores

Sua fazenda emite eventos. Aponte-os para qualquer URL que desejar.

Toda fazenda eventualmente quer algo que nenhum fornecedor envia: um painel na TV do celeiro, um controlador de irrigação caseiro que reaja a alertas, um script de relatório do condado, uma ponte para um software do qual nunca ouvimos falar. A resposta usual é pesquisar uma API em um cronômetro e esperar que você não tenha perdido nada entre as pesquisas.

A melhor resposta é aquela que os sistemas de produção usam entre si: quando algo acontece, empurre, assine e tente novamente até que acerte.

Como realmente funciona

FarmHub POSTs assinam JSON para qualquer URL HTTPS que você configurar, sempre que ocorrerem os eventos de seu interesse.

  • Seis tipos de eventos, empurrados à medida que acontecem. Colheita registrada, alerta gerado, alerta resolvido, ação corretiva resolvida, recall iniciado e relatório gerado. Cada evento é postado em seu endpoint como JSON com o nome do evento em um cabeçalho.
  • Cada carga útil é assinada por HMAC-SHA256. FarmHub gera uma chave de assinatura para a conexão e assina cada corpo da solicitação, enviando a assinatura em um cabeçalho X-FarmHub-Signature. Recalcule o HMAC sobre o corpo bruto e compare. Se não corresponder, não é nosso.
  • Novas tentativas de entrega com espera. Se o seu endpoint estiver inativo ou retornar um erro, o FarmHub tentará novamente com espera. Cada entrega carrega um cabeçalho de ID de entrega exclusivo para que seu manipulador possa desduplicar novas tentativas.
  • As cargas têm controle de versão e você controla a atualização. Quando o formato da carga útil muda, a versão é alterada e as conexões existentes permanecem fixadas em sua versão até que você aceite. Sua integração não é interrompida porque enviamos um campo.

É o mesmo mecanismo de entrega por trás de nossas integrações Slack, Teams e PagerDuty, com o destino entregue a você.

COM QUE VOCÊ PODE CONTAR

Com o que você pode contar

As garantias, justamente:

  • FarmHub gera a chave de assinatura. A chave HMAC é criada no momento da conexão e armazenada criptografada na conexão. Não há segredo global compartilhado e a rotação da chave de uma conexão afeta apenas essa conexão.
  • Cabeçalhos criados para manipuladores reais. Cada solicitação carrega a assinatura, o nome do evento e um ID de entrega exclusivo, para que você possa verificar, rotear e desduplicar sem analisar o corpo primeiro.
  • Interruptor de desligamento. Desative a conexão instantaneamente e as entregas serão interrompidas. Útil quando seu endpoint está se comportando mal ou você está alternando a infraestrutura.
  • Linhas de auditoria encadeadas por hash. Cada tentativa de entrega é registrada em um log de auditoria cujas linhas são encadeadas por hash, portanto, o histórico do que foi enviado para onde é inviolável.

O que não fazemos

Os limites honestos:

  • A entrega é feita pelo menos uma vez, não exatamente uma vez. Novas tentativas significam que seu gerenciador poderá ver uma entrega duas vezes. Desduplicar o ID de entrega.
  • Webhooks são apenas de saída. Esta integração não aceita dados de entrada; ele conta aos seus sistemas o que aconteceu no FarmHub.
  • Os seis tipos de eventos acima são os que serão lançados hoje. Preferimos listar seis acontecimentos reais do que prometer um catálogo que não construímos.

Configuração, honestamente

Você precisa de um endpoint HTTPS que possa receber um JSON POST.

  1. No FarmHub, abra Integrações, escolha Webhook personalizado e insira o URL do seu endpoint. FarmHub gera a chave de assinatura HMAC.
  2. Em seu manipulador, verifique o cabeçalho X-FarmHub-Signature recalculando HMAC-SHA256 no corpo da solicitação bruta com a chave de assinatura.
  3. Responda com um 2xx rapidamente; faça processamento pesado assíncrono. As respostas não 2xx são repetidas com espera.
  4. Acione uma entrega de teste e confirme se a verificação de sua assinatura foi aprovada antes de confiar no feed.

Perguntas que os agricultores fazem

Como posso verificar se um webhook veio do FarmHub?

Calcule HMAC-SHA256 no corpo da solicitação bruta usando a chave de assinatura da conexão e compare-a com o cabeçalho X-FarmHub-Signature, que carrega o resumo hexadecimal prefixado com sha256=. Rejeite qualquer coisa que não corresponda.

Em quais eventos posso me inscrever?

Colheita registrada, alerta gerado, alerta resolvido, ação corretiva resolvida, recall iniciado e relatório gerado. O nome do evento chega no cabeçalho X-FarmHub-Event.

O que acontece se meu endpoint estiver inativo?

FarmHub tenta novamente a entrega com espera. Como a entrega ocorre pelo menos uma vez, seu manipulador deve desduplicar usando o cabeçalho de id X-FarmHub-Delivery.

As alterações na carga útil interromperão minha integração?

Não. As cargas úteis são versionadas e sua conexão permanece fixada em sua versão de carga útil até que você opte pela nova.

Posso girar a chave de assinatura?

Cada conexão possui sua própria chave gerada pelo FarmHub armazenada criptografada. A reconexão emite uma nova chave e o interruptor de interrupção interrompe as entregas instantaneamente enquanto você gira.

PRONTO PARA O PRÓXIMO TURNO

Construir aquilo que não pensamos

Aponte o fluxo de eventos assinado do FarmHub em seu próprio endpoint e conecte o farm a tudo o que você puder imaginar: o painel do celeiro, o controlador, o bot de relatório. Você não precisa de nossa permissão, apenas de uma URL.

Comece gratuitamente