A ferramenta Wait for Webhook permite que o Fin pause no meio do procedimento e aguarde uma entrada externa. Use-a para automatizar processos que exigem integração com sistemas de terceiros como Onfido e Plaid, possibilitando processamento assíncrono.
Nota:
Wait for Webhook está disponível apenas dentro de etapas de Instrução. Adicione-a digitando @ dentro de uma etapa 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 de forma assíncrona, em vez de retornar uma resposta imediatamente.
Casos de uso comuns incluem:
Verificação de identidade ou idade — aguardando um provedor KYC (Conheça Seu Cliente) 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 depósito 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:
Quando uma execução de procedimento começa, o Fin gera uma URL de callback única para cada ferramenta Wait for Webhook.
Configure seu procedimento para passar essa URL de callback para seu sistema externo usando um Data Connector antes que o Fin alcance a ferramenta Wait for Webhook.
Uma vez que o sistema externo conclui seu processamento e envia um webhook para a URL de callback, o Fin captura o payload do webhook nos atributos de resposta configurados e retoma o procedimento automaticamente.
Se nenhum callback for recebido dentro do tempo de espera configurado, o Fin envia a mensagem de escalonamento configurada e atribui a conversa ao responsável pelo escalonamento configurado.
Importante: A URL de callback é única por execução de 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 uma etapa de Instrução, digite @ para abrir o seletor de ferramentas.
Selecione Wait for Webhook da lista.
A ferramenta Wait for Webhook é inserida na etapa 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"). Esse nome identifica a ferramenta no editor e é referenciado quando você mapeia a URL de callback como parâmetro no seu Data Connector.
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 etapas posteriores usando a ferramenta Read attribute.
Por exemplo, se seu provedor de verificação de identidade retorna um status e um reference_id, adicione ambos como atributos de resposta aqui.
Tempo de espera e fallback
Defina quanto tempo o Fin deve esperar por um callback antes de escalar. Você também deve configurar a mensagem de escalonamento enviada ao cliente e selecionar o responsável para quem a conversa será encaminhada se o tempo limite for atingido.
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 tempo limite 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 etapa anterior, incluindo a primeira. Para passar a URL, use um Data Connector.
Configure um Data Connector que chame a API do seu sistema externo (por exemplo, um endpoint "Start ID Verification").
Configure o Data Connector para aceitar uma URL de callback como parâmetro de entrada.
No editor de procedimentos, mapeie esse parâmetro de entrada para o atributo URL da ferramenta webhook.
Certifique-se de que o procedimento está configurado para chamar esse Data Connector antes de alcançar a ferramenta Wait for Webhook.
Quando o Fin chama o Data Connector, ele passa a URL de callback única na requisição. Seu sistema externo armazena essa URL e envia o callback do webhook para ela assim que o processamento for concluído.
Nota: A chamada ao data connector que passa a URL de callback deve acontecer antes da ferramenta Wait for Webhook. Isso permite que o sistema externo tenha acesso à URL de callback.
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 Read attribute em uma etapa 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 uma etapa de Condição para ramificar o fluxo com base no resultado.
Passe valores da resposta para outro Data Connector 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 a próxima etapa. 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 tempo limite. A escalada sempre segue estes dois passos:
Mensagem de escalonamento: A mensagem que o Fin envia ao cliente quando o tempo limite é acionado.
Responsável pelo escalonamento: A equipe ou colega para quem a conversa é encaminhada 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 de chegar aos 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.
Importante: No Preview e Test Fin, esta etapa não espera um callback real do webhook — ela é resolvida imediatamente usando o valor padrão configurado para cada atributo. Para testar o comportamento real de espera/tempo limite, use Simulações ou contate o suporte para habilitar callbacks de visualização ao vivo para seu workspace.
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 encaminha a conversa para o responsável pelo escalonamento. O procedimento não continua.
Como obtenho a URL de callback para meu sistema externo?
Como obtenho a URL de callback para meu sistema externo?
Use uma etapa Data Connector colocada 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 de 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 nem 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 etapas 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 tempo limite seja acionado.
Dica: Sempre adicione uma etapa 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 a etapa no link que enviamos.” Sem isso, o Fin ficará silencioso no meio da conversa sem explicação para o cliente.
Quais permissões eu preciso para usar Wait for Webhook?
Quais permissões eu preciso para usar Wait for Webhook?
Você precisa da permissão can manage workspace data para criar ou editar Procedimentos Fin, incluindo adicionar a ferramenta Wait for Webhook. Você pode verificar e atualizar permissões em Configurações > Workspace > Colegas.