Saltar al contenido principal

​
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: 
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: 
{
  "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: 
{
  "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.

​
¿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. La ruta de invocación por API puede devolver un estado running: 
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "running",
  "webhook_secret": "YOUR_WEBHOOK_SECRET"
}
Con alta concurrencia, también puede devolver un estado queued: 
{
  "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: 
{
  "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: 
{
  "error": "callback_url is required when async is enabled"
}

{
  "error": "callback_url must be a valid URL"
}

​
¿Qué eventos de callback emite Fetch Hive?

Cada entrega por callback tiene el mismo sobre: 
{
  "event_type": "<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: 
{
  "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.

​
¿Dónde inspecciono la entrega por callback después de que inicia?

Usa Registros 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. Consulta también: Ejecutar con API, Registros y Manejo de errores