> ## Documentation Index > Fetch the complete documentation index at: https://docs.fetchhive.com/llms.txt > Use this file to discover all available pages before exploring further. # Entrega por callback y disparadores de webhook > Inicia deployments de flujos de trabajo con invocación por API o disparadores de webhook, envía los resultados a URLs de callback y verifica la entrega de callbacks firmados # Entrega por callback y disparadores de webhook Fetch Hive separa cómo se inicia una ejecución de cómo regresa el resultado: * **Invocación por API** inicia una ejecución a través de `POST /v1/workflow/invoke` con una clave de API del workspace. * **Disparador de webhook** inicia una variante desplegada a través de `POST /v1/workflow/webhooks/...` con el secreto del webhook del deployment. * **Entrega por callback** devuelve respuesta inmediatamente y, más tarde, envía un evento de finalización firmado a `async.callback_url`. El campo de la solicitud sigue llamándose `async` por compatibilidad con la API, pero el comportamiento del producto es entrega por callback. ## Resumen El asistente de deployment de flujos de trabajo expone la invocación por API y los disparadores de webhook para la variante de deployment seleccionada. Los disparadores de webhook usan el secreto del webhook del deployment y no requieren una clave de API del workspace. Las solicitudes de invocación por API pueden elegir entre entrega directa o entrega por callback. Cuando incluyes `async.callback_url`, Fetch Hive devuelve respuesta inmediatamente y, más tarde, entrega un evento de callback firmado a esa URL. Los disparadores de webhook siempre usan entrega por callback. Requieren `async.callback_url`, devuelven respuesta rápidamente y entregan el resultado final únicamente a través del evento de callback firmado. El mismo secreto del deployment se usa en ambas direcciones. Quien hace la llamada demuestra que puede iniciar el flujo de trabajo desplegado enviando el secreto en `X-Fetch-Hive-Webhook-Secret`. Tu receptor de callbacks demuestra que el evento posterior provino de Fetch Hive verificando `X-Fetch-Hive-Signature` con HMAC SHA256 y ese mismo secreto. ## ¿Cómo disparo un flujo de trabajo mediante webhook? Abre **More** en la barra lateral de flujos de trabajo y haz clic en **Get Code**, o abre **Code Snippet** desde una página de deployment de flujo de trabajo. Selecciona el **Deployment** y la **Variant** que quieras disparar, luego abre la pestaña **Webhook trigger**. Copia la URL del webhook y envía una solicitud `POST` con el secreto del deployment en `X-Fetch-Hive-Webhook-Secret`: ```bash theme={null} curl 'https://api.fetchhive.com/v1/workflow/webhooks/YOUR_WORKFLOW_ENDPOINT_ID/variants/YOUR_VARIANT_ID' \ -H 'X-Fetch-Hive-Webhook-Secret: YOUR_WEBHOOK_SECRET' \ -H 'Content-Type: application/json' \ --data-raw '{ "inputs": { "topic": "State of enterprise AI in 2026" }, "async": { "callback_url": "https://example.com/callback" } }' ``` Si tu proveedor de webhook no puede enviar encabezados personalizados, puedes pasar `?secret=YOUR_WEBHOOK_SECRET` como alternativa. Prefiere el encabezado siempre que el proveedor lo admita. Usa el secreto del webhook del deployment que se muestra en el asistente. Es el mismo secreto que Fetch Hive utiliza para firmar los eventos de entrega por callback de este deployment. Cuando el cuerpo tiene un objeto `inputs`, Fetch Hive usa ese objeto como entradas iniciales del flujo de trabajo. Si el cuerpo es un objeto JSON sin `inputs`, Fetch Hive trata todo el objeto como entradas del flujo de trabajo. También puedes incluir los campos opcionales `user` y `metadata` junto a `inputs`. El campo `async.callback_url` es obligatorio: ```json theme={null} { "inputs": { "topic": "State of enterprise AI in 2026" }, "user": { "id": "user_123", "email": "person@example.com" }, "metadata": { "source_system": "zapier" }, "async": { "callback_url": "https://example.com/callback" } } ``` `metadata` es metadata de usuario definida por quien llama, para auditoría y filtrado de registros. Debe ser un objeto plano cuyos valores sean cadenas, números, booleanos o `null`; los objetos anidados y arreglos devuelven un error de validación antes de que comience la ejecución. Para enviar metadata, usa la forma envuelta del cuerpo mostrada arriba con `metadata` junto a `inputs`. Si omites `inputs`, todo el objeto JSON se trata como entradas del flujo de trabajo, por lo que `metadata` no se extrae como metadata para filtrar registros. Las ejecuciones disparadas por webhook aparecen bajo **Source: Webhook** en los registros del flujo de trabajo y muestran **Delivery: Callback** con los registros de entrega por callback. ## ¿Cómo habilito la entrega por callback para la invocación por API? Abre **More** en la barra lateral de flujos de trabajo y haz clic en **Get Code**, o abre **Code Snippet** desde una página de deployment de flujo de trabajo. Selecciona el **Deployment** y la **Variant** que quieras invocar. Activa **Callback delivery**. El fragmento de cURL se actualiza para incluir: ```json theme={null} { "async": { "enabled": true, "callback_url": "https://example.com/callback" } } ``` Reemplaza la URL de callback de ejemplo con tu endpoint real de webhook antes de ejecutar la solicitud. {/* Add screenshot: callback delivery cURL snippet in the workflow get code modal */} ## ¿Cómo verifico las firmas de los callbacks? Activa **Callback delivery** en el cuadro de diálogo del fragmento de código, o abre la pestaña **Webhook trigger**. Copia el **Signing secret** que se muestra debajo del fragmento, o consulta el mismo secreto desde la página de detalles del deployment del flujo de trabajo. Cuando tu servidor reciba el evento de callback, verifica el encabezado `X-Fetch-Hive-Signature` usando HMAC SHA256 y ese secreto de firma. Trata cualquier evento de callback que no pase la verificación de firma como no confiable. Si el flujo de trabajo se inició mediante el disparador de webhook, este secreto de firma es el mismo valor que el sistema disparador envió en `X-Fetch-Hive-Webhook-Secret`. La verificación del disparador entrante es una verificación de secreto tipo bearer; la verificación del callback saliente es la verificación de firma HMAC. ## ¿Qué respuesta obtengo de la entrega por callback? Cuando la entrega por callback está habilitada, la ruta pública responde inmediatamente en lugar de esperar la salida del flujo de trabajo. Para la entrega directa, la API pública espera solo dentro de la ventana de timeout síncrono. Si un flujo de trabajo supera esa ventana, Fetch Hive solicita la cancelación y devuelve `504` con el `request_id` y `run_status: "failed"`. Usa entrega por callback para flujos de trabajo de larga duración o que incluyan pasos Human in the Loop. La ruta de invocación por API puede devolver un estado `running`: ```json theme={null} { "request_id": "req_019d52846ea37682b03522fd0695cc43", "run_status": "running", "webhook_secret": "YOUR_WEBHOOK_SECRET" } ``` Con alta concurrencia, también puede devolver un estado `queued`: ```json theme={null} { "request_id": "req_019d52846ea37682b03522fd0695cc43", "run_status": "queued", "webhook_secret": "YOUR_WEBHOOK_SECRET" } ``` Usa el `request_id` devuelto para el seguimiento de tu propia solicitud y confía en la entrega por callback para el resultado final. Los disparadores de webhook de flujos de trabajo también devuelven respuesta rápidamente: ```json theme={null} { "request_id": "req_019d52846ea37682b03522fd0695cc43", "run_status": "running" } ``` ## ¿Qué reglas de validación se aplican a la entrega por callback? Si `async.enabled` es `true`, `callback_url` es obligatorio. Los disparadores de webhook siempre requieren `async.callback_url`. Fetch Hive también valida que `callback_url` sea una URL válida. Los flujos de trabajo que contienen un paso Human in the Loop siempre requieren entrega por callback, incluso para solicitudes de invocación por API. No pueden completarse de forma síncrona porque Fetch Hive pausa el flujo de trabajo hasta que el miembro del workspace seleccionado responda. Por ejemplo, estos errores están explícitamente confirmados: ```json theme={null} { "error": "callback_url is required when async is enabled" } ``` ```json theme={null} { "error": "callback_url must be a valid URL" } ``` ## ¿Qué eventos de callback emite Fetch Hive? Cada entrega por callback tiene el mismo sobre: ```json theme={null} { "event_type": "", "request_id": "req_...", "data": { "...": "..." } } ``` El campo `event_type` te indica qué estado terminal alcanzó el flujo de trabajo: * `workflow.completed` - el flujo de trabajo finalizó con éxito. `data.output` contiene el valor final de salida. * `workflow.failed` - el flujo de trabajo falló durante la ejecución. `data.error` contiene el mensaje de error. * `workflow.cancelled` - el flujo de trabajo fue cancelado antes de poder completarse, ya sea por un usuario en el dashboard de Fetch Hive o directamente a través del orquestador. `data.error` contiene la razón de la cancelación, y `data.reason` siempre es la cadena `"cancelled"` para que puedas ramificar sin analizar el mensaje. Para flujos de trabajo de generación de imágenes, `workflow.completed` incluye un objeto de salida estructurado: * `data.output.settings` (modelo y ajustes utilizados) * `data.output.assets` (assets generados subidos) Ejemplo de payload `workflow.cancelled`: ```json theme={null} { "event_type": "workflow.cancelled", "request_id": "req_019d52846ea37682b03522fd0695cc43", "data": { "error": "Workflow cancelled: Activity canceled", "reason": "cancelled" } } ``` Trata `workflow.cancelled` como un estado terminal de tu lado. No se entregará ningún evento de callback adicional para ese `request_id`. El progreso parcial de la ejecución del flujo de trabajo, incluidas las completions que terminaron antes de la cancelación, sigue disponible a través de la vista de detalle de la ejecución y los endpoints de [Registros](./logs). ## ¿Dónde inspecciono la entrega por callback después de que inicia? Usa [Registros](./logs) después de que el flujo de trabajo inicie. La vista de detalle de la ejecución del flujo de trabajo puede mostrar la insignia **Callback**, la sección **Callback delivery**, la salida y los **Webhook Logs** para las ejecuciones que usaron entrega por callback. Los **Webhook Logs** son intentos de entrega por callback, no el origen de la ejecución. Si la entrega por callback falla, la vista de registros también puede mostrar el historial de reintentos y los detalles de respuesta de cada intento de entrega. ## Notas Los disparadores de webhook, las solicitudes de invocación por API con entrega por callback y los eventos de callback firmados son partes separadas del ciclo de vida del flujo de trabajo. Un disparador de webhook inicia una ejecución. La entrega por callback controla si Fetch Hive responde inmediatamente y almacena una URL de callback. El evento de callback firmado es la forma en que el resultado final llega a esa URL de callback más tarde. Si no necesitas entrega por callback, mantenla deshabilitada y usa la respuesta directa normal documentada en [Ejecutar con API](./run-with-api). Consulta también: [Ejecutar con API](./run-with-api), [Registros](./logs) y [Manejo de errores](./error-handling)