Webhook

Um dia de trabalho, dos dois jeitos

Pense em quem atualiza a caixa de entrada a cada cinco minutos esperando um e-mail importante, comparado a quem liga a notificação do celular. Num dia de oito horas chegam cinco pagamentos. Na linha de cima, a sua automação pergunta de tempos em tempos "chegou alguma coisa?". Na de baixo, ela é avisada. Mude o intervalo das perguntas e rode o dia. Os pontos vazios são perguntas que voltaram com "nada novo".

Perguntar menos vezes economiza pedidos e aumenta o atraso. Perguntar mais reduz o atraso e desperdiça pedidos. Ser avisado sai da troca.

Cada pergunta é o fluxo rodando: uma execução (cada vez que o fluxo roda do começo ao fim, que é como muitas ferramentas medem o uso). Conta até a que volta com “nada novo”. E quem pergunta é a sua ferramenta, indo até o aplicativo: o aplicativo não avisa nada, só responde quando perguntado. Com o intervalo escolhido no controle deslizante, a conta de um dia inteiro:

A regra prática: o intervalo acompanha o ritmo do que chega. Se chegam poucos e-mails por dia, perguntar de hora em hora basta; perguntar de minuto em minuto gasta execuções à toa.

Você dá o endereço; o outro lado toca quando acontece

Webhook é a campainha da sua casa: fica esperando, e quando alguém aperta, você sabe na hora. O que você entrega ao outro sistema é um endereço de internet que é seu. Siga um aviso do começo ao fim.

O aviso chega num pacote, e os seus dados estão num compartimento

Quem toca a campainha costuma trazer uma encomenda: tem a etiqueta de fora, o remetente, e o que interessa vem dentro da caixa. Quando alguém preenche o formulário de contato, o seu endereço recebe um pacote com várias partes, escrito em JSON (o formato de ficha, com nome e valor, que os sistemas trocam). O que a pessoa preencheu não fica solto: fica dentro de uma parte chamada corpo. Clique nas partes para ver o que cada uma traz e como se chega nela.

O formato do pacote está explicado na página JSON. O caminho com pontos, body.nome, é a mesma ideia de pasta dentro de pasta.

O endereço de teste não é o de verdade

Pense numa campainha com dois botões: um provisório, que só toca enquanto você está montando a casa, e o definitivo. Se o botão que você mostrou às visitas foi o provisório, depois da montagem ninguém ouve. Muitas ferramentas de automação dão dois endereços para a mesma campainha. Um serve para testar enquanto você monta; o outro, o de produção, para o uso de verdade. O erro mais comum é cadastrar o de teste no outro sistema e esquecer de trocar. Ligue e desligue as duas chaves e toque a campainha.

Quem tocou a campainha pode estar esperando uma resposta

Às vezes quem toca a campainha só deixa a encomenda; às vezes fica na porta esperando você atender, e vai embora se você demorar demais. Na maior parte das vezes basta dizer "recebi". Às vezes, quem chamou precisa de conteúdo de volta: o chat espera o texto para mostrar, o site espera a confirmação. E quem espera desiste depois de um tempo, em geral perto de trinta segundos. Escolha o jeito de responder e o tempo que o seu fluxo leva.

Gatilho agendado ou webhook?

Na rotina do escritório, umas tarefas têm hora marcada, como o relatório de segunda, e outras começam porque algo aconteceu, como o cliente ligar. Toda automação começa com um gatilho (o que a faz começar). Agendado é o relógio: roda num horário fixo. Webhook é o aviso: roda quando outro sistema chama. A pergunta que decide é "o que dispara isto: uma hora do dia, ou algo que aconteceu lá fora?".

Sete conferências antes de deixar a campainha ligada

Campainha nova se confere antes de a visita chegar: o fio trocado não aparece quando você mesmo aperta; aparece no dia em que alguém toca e ninguém ouve. Quase todo problema com webhook aparece depois que tudo funcionou no teste. Marque o que já conferiu, e copie a lista para usar no seu próximo fluxo.

O verbo é o mesmo da página API. O fluxo está ativado e o aviso não chegou? Confira o verbo antes de mexer em mais nada: a mensagem de erro costuma dizer, com todas as letras, que o endereço não está registrado para aquele verbo.

Três ideias

Webhook

Um endereço seu que outro sistema chama quando algo acontece, levando os dados junto.

Perguntar de tempos em tempos (polling)

Consultar outro sistema em intervalo fixo para saber se há novidade. Funciona, mas atrasa e desperdiça pedidos.

Gatilho

O que faz uma automação começar: um horário, um clique, um aviso.

Corpo (body)

A parte do pacote que traz os dados do aviso: o que foi preenchido, pago ou marcado.

Endereço de teste

Endereço que só recebe enquanto você está escutando, para montar o fluxo.

Endereço de produção

Endereço que recebe sempre, desde que o fluxo esteja ativado.

Tempo limite (timeout)

Quanto quem chamou espera pela resposta antes de desistir.

Execução

Cada vez que o fluxo roda, do começo ao fim. Cada pergunta de tempos em tempos é uma, mesmo quando não acha nada.

Simplificação didática. O dia com cinco pagamentos, os intervalos e os atrasos são ilustrativos: mostram a forma, não a medida. O limite de espera varia de sistema para sistema; trinta segundos é uma ordem de grandeza comum. Nomes de botões e endereços variam entre ferramentas; a ideia de um endereço de teste e outro de produção é o que se repete.