Webhooks para software de aluguer: como as integrações em tempo real mantêm os sistemas sincronizados

Se alguma vez construiu uma integração entre dois sistemas, provavelmente escreveu código que faz mais ou menos isto: a cada cinco minutos, chamar a API, obter os pedidos mais recentes, compará-los com o que já tem e perceber o que mudou. A isto chama-se polling, e é a abordagem por defeito porque é simples. Também é pouco eficiente.

Na maior parte das vezes, nada mudou. Faz o pedido, recebe uma resposta idêntica à anterior, e descarta-a. Repita isto a cada cinco minutos, 288 vezes por dia, para cada conta que está a sincronizar, e está a consumir chamadas à API, consultas à base de dados e ciclos de processamento para descobrir, quase sempre, que não aconteceu nada.

Pior ainda, o polling é lento por natureza. Se consultar a cada cinco minutos, o melhor cenário entre algo acontecer e o seu sistema descobrir é próximo de zero, e o pior cenário fica mesmo abaixo dos cinco minutos. Consultar com menos frequência para poupar recursos torna esse pior cenário ainda pior. Não há forma de ter simultaneamente eficiência e imediatismo com o polling, está sempre a trocar um pelo outro.

Um webhook inverte essa relação. Em vez de o seu sistema perguntar repetidamente se algo mudou, é o sistema de aluguer que avisa no momento em que algo acontece realmente. Deixa de pagar o custo de perguntar e passa a pagar apenas pelos momentos que importam.

Um webhook é um simples pedido HTTP, normalmente um POST, que um sistema envia automaticamente a outro quando ocorre um evento específico, em vez de um pedido que envia quando lhe apetece verificar. Regista um URL, um endpoint no seu próprio servidor, junto do sistema de que quer receber informação, e quando ocorre um evento relevante do lado deles, esse sistema faz um pedido a esse URL com informação sobre o que aconteceu.

Essa é a distinção fundamental face a uma chamada API normal. Um pedido API habitual é do tipo pull: decide quando perguntar, e o sistema só responde quando é questionado. Um webhook é do tipo push: o sistema decide quando avisar, com base nos seus próprios eventos, não no calendário de quem integra. O pedido tem origem num evento, não num cliente que quer saber algo naquele preciso momento.

Na prática, isto muda completamente a forma do código de integração. Em vez de um ciclo que obtém dados e os compara, escreve um pequeno gestor que recebe um pedido, verifica que provém realmente do sistema esperado, e reage consoante o evento descrito. A Renttix, por exemplo, expõe endpoints de webhook como parte da sua API para programadores, permitindo que uma empresa registe um URL e seja avisada em vez de ter de continuar a perguntar.

A ineficiência do polling agrava-se, não melhora, à medida que um negócio de aluguer cresce. Um único depósito que sincroniza um punhado de encomendas com uma ferramenta externa pode dar-se ao luxo de consultar a cada poucos minutos sem que ninguém note o desperdício. Mas acrescente mais depósitos, mais integrações e mais sistemas externos que precisam de conhecer a atividade de encomendas e pagamentos, e o número de pedidos de verificação de alterações multiplica-se rapidamente, a maioria continuando a ser respondida com um não.

Existe também um limite prático: as APIs têm limites de frequência por boas razões, e uma estratégia de polling suficientemente agressiva para parecer próxima do tempo real acaba frequentemente por embater nesses limites antes de sequer se aproximar de resultados em tempo real. Acaba-se por ajustar a frequência de polling como um compromisso entre carga do servidor, limites de frequência e o grau de desatualização aceitável dos dados, e nenhum desses compromissos se torna mais fácil com o tempo.

Os webhooks evitam por completo esse compromisso. O volume de notificações recebidas é proporcional ao número de coisas que realmente acontecem, não à frequência com que se sente necessidade de perguntar. Uma semana calma gera praticamente nenhum tráfego de webhooks; uma semana intensa gera exatamente tantas notificações quantos os eventos que existem, nem mais uma.

O valor dos webhooks não está no mecanismo em si, mas no que se torna praticável a partir do momento em que os tem. De um modo geral, um sistema de aluguer pode usar webhooks para avisar um sistema externo no momento em que algo muda: por exemplo, quando o estado de uma encomenda avança, um pagamento é cobrado, ou uma devolução é marcada como concluída. O que importa para quem constrói a integração é que a notificação chegue perto do momento em que o evento realmente ocorreu, em vez de só depois de um intervalo de polling potencialmente longo.

Como exemplo ilustrativo, imagine uma empresa de aluguer que construiu o seu próprio painel interno para a equipa de operações, uma vista em ecrã grande do que está alugado, do que deve ser devolvido, e do que já foi pago. Sem webhooks, manter esse painel atualizado significa martelar a API a cada dois minutos, na maioria das vezes sem novidades. Com webhooks, o backend do painel limita-se a escutar os eventos que lhe interessam e a atualizar o registo relevante no momento em que chega uma notificação. O ecrã mantém-se preciso sem estar constantemente a perguntar.

O mesmo padrão aplica-se a quase qualquer sistema externo que valha a pena ligar: uma ferramenta financeira que precisa de saber quando um pagamento é recebido, uma plataforma de suporte que quer sinalizar uma encomenda assim que algo muda nela, ou um pipeline de relatórios personalizado que prefere ser avisado a ter de ir verificar. Os eventos concretos que uma dada plataforma de aluguer expõe variam; o que importa aqui é a forma da integração, não uma lista fixa de tipos de evento.

Os webhooks introduzem um novo modo de falha que o polling não tem: a notificação pode não chegar, e nenhum dos lados se apercebe necessariamente de imediato. O seu endpoint pode estar em baixo durante um minuto durante um deployment. Uma falha de rede pode perder um pedido. O seu próprio código pode gerar um erro a meio do processamento de um payload. Se não conseguir ver nada disso, fica a depurar às cegas, a adivinhar se o sistema de aluguer sequer tentou avisá-lo, e a adivinhar o que enviou.

É aqui que os registos de entrega mostram o seu valor. Um registo das entregas de webhooks permite a um programador ver, a posteriori, o que foi realmente enviado e se foi recebido, em vez de depender de deduções a partir de sintomas a jusante, como um painel que deixou silenciosamente de se atualizar. A API para programadores da Renttix inclui registos de entrega precisamente por esta razão: quando uma integração se comporta mal, a primeira pergunta útil é quase sempre se o webhook foi enviado e o que continha, e um registo de entrega responde a isso diretamente, em vez de o deixar reconstruir a situação a partir dos seus próprios registos de aplicação.

O registo de pedidos é importante pela mesma razão do lado das chamadas à API de uma integração, não só do lado dos webhooks. Entre os registos de entrega para notificações de saída e o registo de pedidos para chamadas à API de entrada, um programador que constrói sobre a API da Renttix tem visibilidade sobre ambas as direções da integração, em vez de ver apenas a sua própria metade.

Os webhooks tratam da parte de avisem-me quando algo acontece de uma integração, mas a maioria das integrações reais também precisa de chamar a API diretamente, para obter detalhes adicionais, consultar algo ou escrever dados de volta. Isso implica uma chave de API, e as chaves de API merecem o mesmo cuidado que o design de webhooks à sua volta.

A definição de âmbito é importante porque uma integração só deve poder fazer aquilo de que realmente precisa. Uma chave gerada para uma integração de relatórios só de leitura não deveria também poder modificar encomendas; uma chave usada por uma ferramenta financeira que só precisa de dados de pagamento não deveria ter acesso ao resto da conta. Chaves com âmbito limitado significam que, se uma integração for comprometida, o dano fica limitado ao que essa chave específica estava autorizada a tocar, não à conta inteira.

A revogabilidade importa no momento em que algo corre mal, ou simplesmente quando uma integração é retirada de serviço. Uma chave que pode ser revogada instantaneamente, sem afetar o acesso de nenhuma outra integração, significa que uma chave comprometida ou obsoleta deixa de funcionar no momento em que decidir, em vez de permanecer como um risco constante porque rodá-la quebraria três outras coisas. A API para programadores da Renttix emite chaves com âmbito limitado e revogáveis precisamente por esta razão: o webhook e a chave são as duas metades do mesmo design de integração segura, não questões separadas.

Existe um padrão mais antigo que isto substitui: exportar dados de um sistema de aluguer periodicamente, um CSV, um relatório agendado, uma descarga manual, e reconstruir a partir dessa fotografia aquilo de que realmente se precisava. Funciona, mas está sempre desatualizado no momento em que é gerado, e transforma cada integração num pequeno projeto de engenharia de dados.

Uma API REST documentada muda essa relação. A Renttix expõe uma API REST documentada em /api/v1, o que significa que uma integração é construída sobre uma interface estável e descrita, em vez de sobre a forma que uma exportação pontual acabe por ter. Combinado com webhooks para notificação em tempo real e registos de entrega mais registo de pedidos para visibilidade em ambas as direções do tráfego, as peças estão reunidas para construir algo mais próximo de uma ligação em direto entre sistemas do que de um despejo periódico de dados.

Nada disto exige um grande esforço de engenharia para obter valor. Um único endpoint de webhook que reage a um tipo de evento, apoiado por uma chave de âmbito limitado que só pode fazer o que essa integração precisa, já representa uma posição significativamente melhor do que um ciclo de polling ou uma exportação noturna, e é um padrão que pode ser alargado uma integração de cada vez, à medida que a necessidade cresce.

O ponto de partida prático é pequeno: escolha a única informação que um sistema externo realmente precisa de conhecer em tempo real, registe um endpoint de webhook para ela, e gere uma chave de API com âmbito limitado apenas ao que essa integração toca. Observe os registos de entrega enquanto testa, para ver o que está realmente a ser enviado em vez de adivinhar.

A partir daí, o padrão expande-se naturalmente, mais eventos, mais integrações, cada uma com a sua própria chave de âmbito limitado, sem nunca voltar a um ciclo que faz a mesma pergunta a cada poucos minutos. Se está a ponderar como os webhooks e a API se encaixariam na sua própria configuração, fale com a equipa sobre o que quer ligar.