Use este artigo para configurar a ferramenta Wait for Webhook em um Procedimento Fin, definir quanto tempo o Fin espera pela resposta de um sistema externo e solucionar problemas caso um callback nunca chegue. A ferramenta Wait for Webhook pausa o Fin no meio do procedimento para que ele possa aguardar uma entrada externa de sistemas que processam solicitações de forma assíncrona, como provedores de verificação de identidade (ex.: Onfido) ou integrações de pagamento e bancárias (ex.: Plaid), antes de retomar.
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
Approval workflows — aguardando uma equipe interna aprovar um reembolso ou exceção
O que acontece quando o Fin alcança a ferramenta Wait for Webhook
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. Ela 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 na 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 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 de 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 solicitaçã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 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 faz o handoff — não há ramificação condicional no próprio tempo limite. O cliente vê primeiro a mensagem de tempo limite configurada, depois a conversa é passada para o destino configurado:
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.
Depois que seu procedimento estiver 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 defina critérios de sucesso com base no caminho do procedimento que você espera que o Fin siga.
Importante: No Preview e Test Fin, esta etapa não espera por um callback real de 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 entre em contato com o suporte para habilitar callbacks de visualização ao vivo para seu workspace.
Quais são as limitações da ferramenta Wait for Webhook?
A ferramenta Wait for Webhook tem as seguintes limitações em sua versão atual:
Somente valores escalares: Os atributos de resposta suportam apenas valores de texto e número. Arrays e objetos JSON aninhados no payload do webhook não são capturados.
Correspondência de atributos sensível a maiúsculas e minúsculas: O nome de um atributo de resposta deve corresponder exatamente à chave correspondente no payload do webhook. Se os nomes não corresponderem, esse valor não é capturado — e nenhum erro é exibido, então verifique os nomes dos atributos cuidadosamente se um valor retornar vazio.
Reutilização da URL de callback em loop-back: Se um procedimento retornar à mesma ferramenta Wait for Webhook mais de uma vez em uma única execução, a mesma URL de callback é reutilizada para essa ferramenta.
Separado dos Workflows: A ferramenta Wait for Webhook em Procedimentos Fin é uma implementação separada da etapa Wait for Webhook em Workflows. A configuração não é compartilhada nem reutilizável entre os dois.
FAQs
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 tempo limite — ele envia a mensagem de tempo limite configurada ao cliente e faz o handoff para o destino configurado, que pode ser uma equipe ou um workflow. O procedimento não continua; se o handoff for para um workflow, o workflow decide o que acontece a seguir e o procedimento não é retomado.
Como obtenho a URL de callback para meu sistema externo?
Como obtenho a URL de callback para meu sistema externo?
Use uma etapa de 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 de 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 nenhuma 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 de equipe.