Use este artigo para adicionar a ferramenta Wait for Webhook a um Procedimento Fin, configurá-la para pausar e aguardar a resposta de um sistema externo, e definir o comportamento de timeout e escalonamento.
Wait for Webhook pausa um Procedimento Fin e espera que um sistema externo envie um webhook, uma notificação HTTP automatizada que um sistema envia para outro quando um evento específico ocorre, antes que o Fin retome. Cada conversa recebe uma URL de callback única (um endereço web dedicado que o Fin gera para essa conversa), que seu sistema externo usa para enviar sua resposta de volta ao Fin. Isso possibilita integrar com serviços de terceiros que processam solicitações assincronamente — como provedores de verificação de identidade, processadores de pagamento ou sistemas de aprovação — sem perder o contexto da conversa em andamento.
Nota:
Wait for Webhook está atualmente em beta. Para habilitá-lo em seu workspace, entre em contato com a equipe de suporte para solicitar acesso. Você também precisará da permissão can manage workspace data para criar ou editar Procedimentos Fin.
Wait for Webhook está disponível apenas dentro de passos de Instrução. Adicione-o digitando @ dentro de um passo de Instrução e selecionando Wait for Webhook no seletor de ferramentas.
Quando usar Wait for Webhook
Use esta ferramenta quando seu procedimento precisar passar para um sistema externo e aguardar um resultado antes de continuar — e esse sistema processar solicitações assincronamente em vez de retornar uma resposta imediatamente.
Casos de uso comuns incluem:
Verificação de identidade ou idade — aguardando um provedor KYC (Know Your Customer) confirmar a identidade do cliente
Autorização de pagamento — aguardando um processador de pagamento confirmar uma transação
Vinculação de conta — aguardando a conclusão de um fluxo OAuth (padrão aberto de autorização)
Verificações de cumprimento de pedido — aguardando um sistema de armazém confirmar a disponibilidade de estoque
Workflows de aprovação — aguardando uma equipe interna aprovar um reembolso ou exceção
Como funciona
Quando o Fin alcança uma ferramenta Wait for Webhook em um procedimento, acontece o seguinte:
O Fin gera uma URL de callback única para esta conversa quando o procedimento começa — não quando a execução alcança a ferramenta Wait for Webhook. Esta URL está disponível para qualquer passo no procedimento desde o início.
Seu procedimento (via um Conector de Dados configurado anteriormente no fluxo) passa esta URL de callback para seu sistema externo.
O sistema externo completa seu processamento e envia sua resposta para a URL de callback.
O Fin recebe a resposta, captura o payload nos atributos de resposta definidos na configuração da ferramenta Wait for Webhook, e retoma o procedimento a partir do próximo passo.
Se nenhum callback for recebido dentro do tempo de espera configurado, o Fin aciona a ação de fallback.
Importante: A URL de callback é única por execução do procedimento. Não pode ser reutilizada em múltiplas conversas nem armazenada como um endpoint estático.
Como adicionar Wait for Webhook a um procedimento
Abra seu procedimento no editor.
Dentro de um passo de Instrução, digite @ para abrir o seletor de ferramentas.
Selecione Wait for Webhook da lista.
A ferramenta Wait for Webhook é inserida no passo e um painel lateral de configuração abre à direita.
Como configurar a ferramenta
O painel lateral de configuração do Wait for Webhook tem três campos:
Nome da ferramenta
Dê à ferramenta um nome descritivo (por exemplo, "Wait for ID verification callback"). Este nome identifica a ferramenta no editor e é referenciado quando você mapeia a URL de callback como parâmetro no seu Conector de Dados.
Atributos de resposta
Defina os campos que você espera que o sistema externo inclua no payload do webhook. Cada atributo definido aqui é capturado quando o callback chega e pode ser referenciado em passos posteriores usando a ferramenta Ler atributo.
Por exemplo, se seu provedor de verificação de identidade enviar de volta um status e um reference_id, adicione ambos como atributos de resposta aqui.
Nota: Apenas valores escalares de string são suportados como atributos de resposta — um valor escalar é um único pedaço de texto (por exemplo, "verified" ou "approved"), ao contrário de arrays ou objetos JSON aninhados. Se seu sistema externo enviar um payload complexo e aninhado, transforme-o em valores escalares antes de enviar o callback. Os atributos de resposta devem ser definidos antes do webhook ser acionado e não podem ser adicionados retroativamente depois que o procedimento estiver ativo.
Tempo de espera e fallback
Defina quanto tempo o Fin deve esperar por um callback antes de escalar. Entre em contato com sua equipe da conta Intercom para detalhes sobre os valores mínimos e máximos de tempo de espera. Se nenhum callback for recebido dentro da janela configurada, o Fin sempre escala via um caminho fixo — não há ramificação condicional no timeout. Você deve configurar duas coisas no painel lateral de configuração do Wait for Webhook: uma mensagem de escalonamento para enviar ao cliente, e um responsável pelo escalonamento (uma equipe ou colega) para direcionar a conversa.
Importante: Sempre configure tanto uma mensagem de escalonamento quanto um responsável pelo escalonamento no painel lateral. Se algum deles estiver faltando, o comportamento do timeout pode ser imprevisível.
Como passar a URL de callback para seu sistema externo
A URL de callback é gerada quando o procedimento começa — não quando a execução alcança a ferramenta Wait for Webhook. Isso significa que você pode passá-la para seu sistema externo em qualquer passo anterior, incluindo o primeiro passo. Para passar a URL, use um Conector de Dados.
Configure um Conector de Dados que chame a API do seu sistema externo (por exemplo, um endpoint "Start ID verification").
Na configuração do Conector de Dados, adicione um parâmetro de entrada e mapeie-o para o atributo de callback da ferramenta webhook — esta é a URL de callback gerada dinamicamente para esta conversa.
Adicione um passo Chamar conector de dados em seu procedimento antes da ferramenta Wait for Webhook.
Quando o Fin chama o Conector de Dados, ele passa a URL de callback para seu sistema externo como parte da solicitação.
Seu sistema externo armazena a URL de callback e a usa para enviar o resultado de volta ao Fin via POST assim que o processamento for concluído. Uma vez que o callback é recebido, o Fin retoma o procedimento automaticamente a partir da ferramenta Wait for Webhook.
Nota: O passo do Conector de Dados que passa a URL de callback deve vir antes da ferramenta Wait for Webhook. Como a URL está disponível desde o momento em que o procedimento começa, sua chamada de conector pode ser tão cedo no fluxo quanto você precisar.
Como ler os dados de resposta após o callback
Uma vez que o Fin recebe o callback do webhook e retoma o procedimento, o payload da resposta é capturado nos atributos de resposta que você definiu na configuração da ferramenta Wait for Webhook. Use a ferramenta Ler atributo em um passo de Instrução subsequente para acessar esses valores.
Por exemplo:
Leia verification_status para verificar se a checagem de identidade foi aprovada ou reprovada.
Use um passo de Condição para ramificar o fluxo com base no resultado.
Passe valores da resposta para outro Conector de Dados para processamento adicional.
Uma vez que a ferramenta Wait for Webhook recebeu seu callback e você ramificou com base nos atributos de resposta capturados, o procedimento continua normalmente para o próximo passo. Se o callback nunca chegar dentro do tempo de espera configurado, o Fin escala conforme descrito em 'O que acontece quando o tempo de espera expira?' abaixo.
O que acontece quando o tempo de espera expira?
Quando o tempo de espera configurado da ferramenta Wait for Webhook expira sem receber um callback, o Fin sempre escala. Não há ramificação condicional — você não pode configurar comportamentos diferentes dependendo do timeout. A escalada sempre segue estes dois passos:
Mensagem de escalonamento: A mensagem que o Fin envia ao cliente quando o timeout ocorre.
Responsável pelo escalonamento: A equipe ou colega para quem a conversa é direcionada após o envio da mensagem.
Dica:
Defina seu tempo de espera para corresponder ao tempo de processamento esperado do seu sistema externo, com uma margem razoável. Se seu provedor normalmente responde em 10 segundos, um tempo de espera de 60 segundos oferece uma margem segura mantendo a experiência responsiva.
Uma vez que seu procedimento esteja configurado, use Simulações no editor de Procedimentos para validar o fluxo Wait for Webhook de ponta a ponta antes que ele alcance clientes reais. Defina um payload de callback simulado na simulação e estabeleça critérios de sucesso baseados no caminho do procedimento que você espera que o Fin siga.
Perguntas frequentes
Meu webhook nunca chegou — o que acontece?
Meu webhook nunca chegou — o que acontece?
Se nenhum callback for recebido dentro do tempo de espera configurado, o Fin aciona o caminho de escalonamento — envia a mensagem de escalonamento configurada ao cliente e direciona a conversa para o responsável pelo escalonamento. O procedimento não continua.
Como faço para enviar a URL de callback para meu sistema externo?
Como faço para enviar a URL de callback para meu sistema externo?
Use um passo Conector de Dados colocado antes da ferramenta Wait for Webhook em seu procedimento. Configure o conector para chamar a API do seu sistema externo e mapeie o atributo de callback da ferramenta webhook como um parâmetro de entrada. O Fin passa a URL de callback para o sistema externo quando o conector é chamado, para que o sistema saiba para onde enviar o callback.
Posso usar a mesma URL de callback para múltiplas conversas?
Posso usar a mesma URL de callback para múltiplas conversas?
Não. A URL de callback é única por execução do procedimento e é gerada quando o procedimento começa — não quando a execução alcança a ferramenta Wait for Webhook. Cada vez que um procedimento é executado para um cliente, uma nova URL é gerada. Você não pode armazená-la como um endpoint estático ou reutilizá-la em várias conversas.
Quais campos de payload meu sistema externo pode enviar de volta?
Quais campos de payload meu sistema externo pode enviar de volta?
Seu sistema externo pode incluir quaisquer campos no payload do webhook, mas apenas os campos que você definiu como atributos de resposta na configuração da ferramenta Wait for Webhook são capturados pelo Fin e disponíveis em passos subsequentes. Quaisquer campos adicionais no payload são ignorados.
O que acontece enquanto o Fin está esperando um callback?
O que acontece enquanto o Fin está esperando um callback?
Enquanto o Fin está pausado aguardando um callback do webhook, ele não responde a mensagens recebidas do cliente. A conversa fica efetivamente silenciosa até que o callback chegue ou o timeout ocorra.
Dica: Sempre adicione um passo de Instrução antes da ferramenta Wait for Webhook para informar ao cliente o que está acontecendo — por exemplo, “Estamos verificando sua identidade. Por favor, complete o passo no link que enviamos.” Sem isso, o Fin ficará silencioso no meio da conversa sem nenhuma explicação para o cliente.