Usa este artículo para configurar la herramienta Wait for Webhook en un Procedimiento Fin, ajustar cuánto tiempo Fin espera la respuesta de un sistema externo y solucionar problemas si nunca llega un callback. La herramienta Wait for Webhook pausa Fin a mitad del procedimiento para esperar una entrada externa de sistemas que procesan solicitudes de forma asíncrona, como proveedores de verificación de identidad (p. ej., Onfido) o integraciones de pagos y bancos (p. ej., Plaid), antes de continuar.
Nota:
Wait for Webhook solo está disponible dentro de pasos de Instrucción. Agrégalo 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
Approval workflows: esperar a que un equipo interno apruebe un reembolso o excepción
Qué sucede cuando Fin llega a la herramienta Wait for Webhook
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 de configuración lateral a la derecha.
Cómo configurar la herramienta
El panel de configuración lateral 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 Fin debe esperar 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 en el primero. Para pasar la URL, usa un Data Connector.
Configura un Data Connector que llame a la API de tu sistema externo (p. ej., 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 de 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 termina.
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 se agota?' a continuación.
¿Qué sucede cuando el tiempo de espera se agota?
Cuando el tiempo de espera configurado de la herramienta Wait for Webhook expira sin recibir un callback, Fin siempre delega: no hay ramificación condicional por el tiempo de espera. El cliente ve primero el mensaje de tiempo de espera configurado, luego la conversación se delega al destino configurado:
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 ofrece 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 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.
¿Cuáles son las limitaciones de la herramienta Wait for Webhook?
La herramienta Wait for Webhook tiene las siguientes limitaciones en su versión actual:
Solo valores escalares: Los atributos de respuesta solo admiten valores de texto y número. No se capturan arreglos ni objetos JSON anidados en la carga útil del webhook.
Coincidencia de atributos sensible a mayúsculas y minúsculas: El nombre de un atributo de respuesta debe coincidir exactamente con la clave correspondiente en la carga útil del webhook. Si los nombres no coinciden, ese valor no se captura y no se muestra error, así que revisa cuidadosamente los nombres si un valor regresa vacío.
Reutilización de URL de callback en bucles: Si un procedimiento regresa a la misma herramienta Wait for Webhook más de una vez en una sola ejecución, se reutiliza la misma URL de callback para esa herramienta.
Separado de Workflows: La herramienta Wait for Webhook en Procedimientos Fin es una implementación separada del paso Wait for Webhook en Workflows. La configuración no se comparte ni reutiliza entre ambos.
Preguntas frecuentes
Mi webhook nunca llegó, ¿qué sucede?
Mi webhook nunca llegó, ¿qué sucede?
Si no se recibe un callback dentro del tiempo de espera configurado, Fin activa la ruta de tiempo de espera: envía el mensaje de tiempo de espera configurado al cliente y delega al destino configurado, que puede ser un equipo o un workflow. El procedimiento no continúa; si la delegación es a un workflow, este decide qué sucede después y el procedimiento no se reanuda.
¿Cómo obtengo la URL de callback para mi sistema externo?
¿Cómo obtengo la URL de callback para mi sistema externo?
Usa un paso de 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 de 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?
¿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?
¿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?
¿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á pasando, 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?
¿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.