La herramienta Wait for Webhook permite a Fin pausar a mitad del procedimiento y esperar una entrada externa. Úsala para automatizar procesos que requieren integración con sistemas de terceros como Onfido y Plaid, permitiendo procesamiento asíncrono.

Nota:

Wait for Webhook solo está disponible dentro de pasos de Instrucción. Agrégala escribiendo @ dentro de un paso de Instrucción y seleccionando Wait for Webhook en el selector de herramientas.

Cuándo usar Wait for Webhook

Usa esta herramienta cuando tu procedimiento necesite delegar a un sistema externo y esperar un resultado antes de continuar, y ese sistema procese solicitudes de forma asíncrona en lugar de devolver una respuesta inmediata.

Casos de uso comunes incluyen:

Verificación de identidad o edad: esperar a que un proveedor KYC (Conoce a tu Cliente) confirme la identidad del cliente
Autorización de pago: esperar a que un procesador de pagos confirme una transacción
Vinculación de cuentas: esperar a que un flujo OAuth (estándar abierto de autorización) se complete
Verificaciones de cumplimiento de pedidos: esperar a que un sistema de almacén confirme la disponibilidad de stock
Flujos de aprobación: esperar a que un equipo interno apruebe un reembolso o excepción

Cómo funciona

Cuando Fin llega a una herramienta Wait for Webhook en un procedimiento, sucede lo siguiente:

Cuando inicia una ejecución de procedimiento, Fin genera una URL de callback única para cada herramienta Wait for Webhook.
Configura tu procedimiento para pasar esta URL de callback a tu sistema externo usando un Data Connector antes de que Fin llegue a la herramienta Wait for Webhook.
Una vez que el sistema externo completa su procesamiento y envía un webhook a la URL de callback, Fin captura la carga útil del webhook en los atributos de respuesta configurados y reanuda el procedimiento automáticamente.
Si no se recibe un callback dentro del tiempo de espera configurado, Fin envía el mensaje de escalación configurado y asigna la conversación al responsable de escalación configurado.

Importante: La URL de callback es única por ejecución de procedimiento. No puede reutilizarse en múltiples conversaciones ni almacenarse como un endpoint estático.

Cómo agregar Wait for Webhook a un procedimiento

Abre tu procedimiento en el editor.
Dentro de un paso de Instrucción, escribe @ para abrir el selector de herramientas.
Selecciona Wait for Webhook de la lista.
La herramienta Wait for Webhook se inserta en el paso y se abre un panel lateral de configuración a la derecha.

Cómo configurar la herramienta

El panel lateral de configuración de Wait for Webhook tiene tres campos:

Nombre de la herramienta

Dale a la herramienta un nombre descriptivo (por ejemplo, "Wait for ID verification callback"). Este nombre identifica la herramienta en el editor y se referencia cuando mapeas la URL de callback como parámetro en tu Data Connector.

Atributos de respuesta

Define los campos que esperas que el sistema externo incluya en la carga útil del webhook. Cada atributo definido aquí se captura cuando llega el callback y puede referenciarse en pasos posteriores usando la herramienta Leer atributo.

Por ejemplo, si tu proveedor de verificación de identidad devuelve un status y un reference_id, agrega ambos como atributos de respuesta aquí.

Tiempo de espera y alternativa

Configura cuánto tiempo debe esperar Fin por un callback antes de escalar. También debes configurar el mensaje de escalación enviado al cliente y seleccionar al responsable a quien se asignará la conversación si se alcanza el tiempo de espera.

Importante: Siempre configura tanto un mensaje de escalación como un responsable de escalación en el panel lateral. Si falta alguno, el comportamiento del tiempo de espera puede ser impredecible.

Cómo pasar la URL de callback a tu sistema externo

La URL de callback se genera cuando inicia el procedimiento, no cuando la ejecución llega a la herramienta Wait for Webhook. Esto significa que puedes pasarla a tu sistema externo en cualquier paso anterior, incluso el primero. Para pasar la URL, usa un Data Connector.

Configura un Data Connector que llame a la API de tu sistema externo (por ejemplo, un endpoint "Start ID Verification").
Configura el Data Connector para aceptar una URL de callback como parámetro de entrada.
En el editor de procedimientos, mapea este parámetro de entrada al atributo URL de la herramienta webhook.
Asegúrate de que el procedimiento esté configurado para llamar a este Data Connector antes de que llegue a la herramienta Wait for Webhook.
Cuando Fin llama al Data Connector, pasa la URL de callback única en la solicitud. Tu sistema externo almacena esta URL y envía el callback webhook a ella una vez que el procesamiento se completa.

Nota: La llamada al Data Connector que pasa la URL de callback debe ocurrir antes de la herramienta Wait for Webhook. Esto permite que el sistema externo acceda a la URL de callback.

Cómo leer los datos de respuesta después del callback

Una vez que Fin recibe el callback webhook y reanuda el procedimiento, la carga útil de la respuesta se captura en los atributos de respuesta que definiste en la configuración de la herramienta Wait for Webhook. Usa la herramienta Leer atributo en un paso de Instrucción posterior para acceder a estos valores.

Por ejemplo:

Lee verification_status para verificar si la comprobación de identidad fue aprobada o fallida.
Usa un paso de Condición para ramificar el flujo según el resultado.
Pasa valores de la respuesta a otro Data Connector para procesamiento adicional.

Una vez que la herramienta Wait for Webhook ha recibido su callback y has ramificado según los atributos de respuesta capturados, el procedimiento continúa normalmente a su siguiente paso. Si el callback nunca llega dentro del tiempo de espera configurado, Fin escala como se describe en '¿Qué sucede cuando el tiempo de espera expira?' a continuación.

¿Qué sucede cuando el tiempo de espera expira?

Cuando el tiempo de espera configurado para la herramienta Wait for Webhook expira sin recibir un callback, Fin siempre escala. No hay ramificación condicional: no puedes configurar un comportamiento diferente según el tiempo de espera. La escalación siempre sigue estos dos pasos:

Mensaje de escalación: El mensaje que Fin envía al cliente cuando se activa el tiempo de espera.
Responsable de escalación: El equipo o compañero al que se dirige la conversación después de enviar el mensaje.

Consejo:

Configura tu tiempo de espera para que coincida con el tiempo de procesamiento esperado de tu sistema externo, con un margen razonable. Si tu proveedor normalmente responde en 10 segundos, un tiempo de espera de 60 segundos da un margen seguro manteniendo la experiencia ágil.
Una vez que tu procedimiento esté configurado, usa Simulaciones en el editor de Procedimientos para validar el flujo Wait for Webhook de principio a fin antes de que llegue a clientes reales. Define una carga útil de callback simulada en la simulación y establece criterios de éxito basados en la ruta del procedimiento que esperas que Fin siga.

Importante: En Vista previa y Prueba de Fin, este paso no espera un callback webhook real: se resuelve inmediatamente usando el valor predeterminado configurado para cada atributo. Para probar el comportamiento real de espera/tiempo de espera, usa Simulaciones o contacta soporte para habilitar callbacks de vista previa en vivo para tu espacio de trabajo.

Preguntas frecuentes

Mi webhook nunca llegó, ¿qué sucede?

Si no se recibe un callback dentro del tiempo de espera configurado, Fin activa la ruta de escalación: envía el mensaje de escalación configurado al cliente y dirige la conversación al responsable de escalación. El procedimiento no continúa.

¿Cómo obtengo la URL de callback para mi sistema externo?

Usa un paso Data Connector colocado antes de la herramienta Wait for Webhook en tu procedimiento. Configura el conector para llamar a la API de tu sistema externo y mapea el atributo callback de la herramienta webhook como parámetro de entrada. Fin pasa la URL de callback al sistema externo cuando se llama al conector, para que el sistema sepa dónde enviar el callback.

¿Puedo usar la misma URL de callback para múltiples conversaciones?

No. La URL de callback es única por ejecución de procedimiento y se genera cuando inicia el procedimiento, no cuando la ejecución llega a la herramienta Wait for Webhook. Cada vez que un procedimiento se ejecuta para un cliente, se genera una nueva URL. No puedes almacenarla como un endpoint estático ni reutilizarla en conversaciones.

¿Qué campos de carga útil puede enviar mi sistema externo?

Tu sistema externo puede incluir cualquier campo en la carga útil del webhook, pero solo los campos que hayas definido como atributos de respuesta en la configuración de la herramienta Wait for Webhook son capturados por Fin y están disponibles en pasos posteriores. Cualquier campo adicional en la carga útil se ignora.

¿Qué sucede mientras Fin espera un callback?

Mientras Fin está pausado esperando un callback webhook, no responde a mensajes entrantes del cliente. La conversación está efectivamente en silencio hasta que llega el callback o se activa el tiempo de espera.

Consejo: Siempre agrega un paso de Instrucción antes de la herramienta Wait for Webhook para informar al cliente qué está sucediendo — por ejemplo, “Estamos verificando tu identidad. Por favor, completa el paso en el enlace que te enviamos.” Sin esto, Fin quedará en silencio a mitad de la conversación sin explicación para el cliente.

¿Qué permisos necesito para usar Wait for Webhook?

Necesitas el permiso can manage workspace data para crear o editar Procedimientos Fin, incluyendo agregar la herramienta Wait for Webhook. Puedes revisar y actualizar permisos en Configuración > Espacio de trabajo > Compañeros.

Uso de la herramienta Wait for Webhook en Procedimientos Fin