A ferramenta Wait for Webhook permite que o Fin pause no meio do procedimento e espere por uma entrada externa. Use-a para automatizar processos que requerem 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 esperar por 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 — esperando que um provedor KYC (Conheça Seu Cliente) confirme a identidade do cliente
Autorização de pagamento — esperando que um processador de pagamento confirme uma transação
Vinculação de conta — esperando que um fluxo OAuth (padrão aberto de autorização) seja concluído
Verificações de cumprimento de pedido — esperando que um sistema de armazém confirme a disponibilidade de estoque
Workflows de aprovação — esperando que uma equipe interna aprove um reembolso ou exceção
Como funciona
Quando o Fin alcança uma ferramenta Wait for Webhook em um procedimento, o seguinte acontece:
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 Conector de Dados 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 é aberto à 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 um 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 etapas 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.
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 etapa. 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").
Configure o Conector de Dados 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 Conector de Dados antes de alcançar a ferramenta Wait for Webhook.
Quando o Fin chama o Conector de Dados, 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 para o conector de dados 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
Assim 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 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 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 para a próxima etapa normalmente. 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 de espera. A escalada sempre segue estes dois passos:
Mensagem de escalonamento: A mensagem que o Fin envia ao cliente quando o tempo de espera expira.
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.
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 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 uma etapa de Conector de Dados colocada antes da ferramenta Wait for Webhook no 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 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 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 esperando 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 expire.
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.