Por qué no se dispara la devolución de llamada de tu tarea de hiapi y cómo solucionarlo

Por qué no se dispara la devolución de llamada de tu tarea de hiapi

Enviaste una tarea mediante POST https://api.hiapi.ai/v1/tasks incluyendo un objeto callback; la tarea terminó (cuando haces GET /v1/tasks/{taskId} ves status: "success"), pero tu endpoint nunca recibió la notificación del estado final. No llegó ninguna solicitud a tu servidor. Sin reintentos. Nada en los registros.

Las devoluciones de llamada de hiapi se entregan como HTTPS POST de servidor a servidor desde fuera de tu red. Si algo falla en esa ruta —la URL no es accesible desde la internet pública, no se puede negociar TLS, tu manejador no devuelve 2xx con la suficiente rapidez, o tu verificación de firma rechaza la solicitud— entonces, desde el punto de vista de tu aplicación, la notificación es "silenciosa". La buena noticia: casi siempre se trata de uno de unos pocos errores de configuración, y cada uno es fácil de verificar.

Causas comunes (ordenadas por probabilidad)

1. La URL de devolución de llamada no es accesible desde la internet pública. localhost, 127.0.0.1, una IP dentro de tu VPC, o un túnel ngrok ya caducado: hiapi no puede acceder a ellos.
2. Problemas de HTTPS / TLS. Certificado autofirmado, certificado caducado, cadena de certificados incompleta o nombre de host que no coincide. hiapi solo realiza POST a URL que empiezan por https:// y valida la cadena de certificados.
3. Tu manejador no devuelve 2xx dentro del tiempo de espera. Si ejecutas operaciones lentas de forma síncrona dentro del manejador de la devolución de llamada (escrituras en base de datos, descarga de imágenes, envío de notificaciones), la solicitud agotará el tiempo de espera antes de que devuelvas 200. Desde el punto de vista de hiapi, eso es un fallo.
4. Nunca registraste una Webhook Sign Key y tu manejador rechaza las solicitudes sin firmar. Si no generas una clave de firma en Settings, el cuerpo de la solicitud que hiapi entrega no llevará la cabecera de firma; cualquier middleware de verificación que hayas escrito tratará esa solicitud como inválida y la descartará.
5. Omitiste el objeto callback al enviar. Es opcional. Si no lo incluiste en el POST /v1/tasks, no habrá nada que se dispare. Debes consultar en su lugar con GET /v1/tasks/{taskId}.
6. La tarea sigue en ejecución. La devolución de llamada solo se dispara en el estado final (success o fail). Cuando status es queued, handling o archiving, todavía no se envía la devolución de llamada.
7. El host de la URL de devolución de llamada está en una lista de denegación / el cortafuegos de tu empresa bloquea el tráfico saliente hacia él. Menos habitual, pero merece la pena comprobarlo si estás en un entorno de red perimetral estricto.

Cómo solucionarlo: lista de comprobación de 7 pasos

1. Confirma que la tarea realmente alcanzó un estado final. curl -H "Authorization: Bearer $HIAPI_KEY" https://api.hiapi.ai/v1/tasks/tk-hiapi-.... Si status es queued o handling, la devolución de llamada aún no se ha disparado; espera, no depures.
2. Confirma que enviaste el objeto callback. Vuelve a leer el cuerpo de la solicitud que enviaste a POST /v1/tasks. Si falta callback, esa es la respuesta: añádelo y vuelve a enviar, o consulta en su lugar.
3. Prueba la URL de devolución de llamada desde la internet pública. Ejecuta curl -i -X POST https://your.domain.example/hiapi/callback -d '{}' -H "Content-Type: application/json" desde cualquier máquina fuera de tu red (un teléfono con datos móviles, un shell en la nube, una herramienta curl en línea). Debes recibir una respuesta HTTP 2xx de tu propio servidor. Si obtienes conexión rechazada, un error DNS o cualquier respuesta que no sea 2xx, corrige eso primero.
4. Verifica la cadena de certificados TLS. curl -vI https://your.domain.example/hiapi/callback 2>&1 | grep -i 'ssl\|cert'. Busca SSL certificate problem. Si aparece ese error, instala la cadena de certificados completa (certificado hoja + intermedio), o usa un certificado gestionado (Let's Encrypt, CDN, ACM).
5. Devuelve 200 inmediatamente y procesa de forma asíncrona. Dentro de tu manejador: escribe la carga útil de la solicitud en una cola / tabla de datos, devuelve 200 OK y luego procesa el trabajo en un worker en segundo plano. No dejes que la respuesta se bloquee por llamadas descendentes lentas.
6. Genera una Webhook Sign Key y unifica tu forma de verificación. Ve a /en/dashboard/settings → Webhook Sign Key → Generate y guarda la clave. Si tu manejador verifica la firma, usa la clave guardada; si no la verifica, desactiva temporalmente la verificación, confirma que la entrega funciona y vuelve a activarla.
7. Revisa /en/dashboard/logs. El registro de llamadas muestra la solicitud y su estado final. Comparar el request_id de tu registro de llamadas con lo que tu servidor recibió realmente (si recibió algo) es la forma más rápida de localizar si "la devolución de llamada salió de hiapi" o "la devolución de llamada llegó a mi servidor".

Ejemplo mínimo de verificación

Usa lo siguiente para confirmar de extremo a extremo tu clave de API, la ruta de creación de tareas y el endpoint de devolución de llamada. Elige un modelo de imagen rápido para la prueba de humo; según la documentación pública, los ID de modelo incluyen un sufijo de capacidad:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2/text-to-image",
    "input": {"prompt": "a cute cat"},
    "callback": {"url": "https://your.domain.example/hiapi/callback"}
  }'

Deberías recibir inmediatamente una respuesta JSON que contenga un taskId, con la forma tk-hiapi-.... Luego, en cuanto la tarea pase a success o fail, observa los registros de tu servidor para ver si llega un POST entrante a /hiapi/callback. Si el propio paso de creación de la tarea devuelve 401 Unauthorized, entonces el problema está en la clave; consulta Por qué hiapi devuelve 429 (y qué hacer al respecto) para entender cómo funciona el mecanismo de envoltura de errores de hiapi (la misma estructura hiapi_error se aplica a todos los códigos de estado).

Enlaces relacionados

• API Keys — verifica que tu clave es válida y tiene el alcance correcto
• Settings — genera o rota tu Webhook Sign Key
• Call Logs — confirma que hiapi ha enviado la devolución de llamada y el estado de la respuesta
• API Reference — especificación completa de POST /v1/tasks y GET /v1/tasks/{id}
• Límite de tasa 429 de hiapi — análisis detallado de la envoltura de errores para problemas relacionados del tipo "recibí un estado pero no una devolución de llamada"

FAQ

¿hiapi reintenta las devoluciones de llamada fallidas? Una devolución de llamada solo se considera entregada cuando tu endpoint devuelve una respuesta 2xx. Si tu manejador devuelve 5xx, agota el tiempo de espera o falla el handshake TLS, considera la devolución de llamada como no entregada. El patrón más robusto es: para cualquier tarea que hayas enviado con devolución de llamada, usa siempre la consulta GET /v1/tasks/{taskId} como respaldo. Así, incluso un fallo puntual en la ruta de la devolución de llamada no hará que se pierda el resultado.

¿Puede la URL de devolución de llamada usar HTTP en lugar de HTTPS? No. Solo se aceptan URL que empiecen por https://. Si estás probando en local, usa un túnel que termine TLS por ti (Cloudflare Tunnel, ngrok, tailscale funnel) y apunta la devolución de llamada a un endpoint HTTPS público.

¿Por qué mi manejador recibió el cuerpo de la solicitud pero falla la verificación de la firma? O bien (a) generaste la Webhook Sign Key después de enviar la tarea —la solicitud se firmó con la clave antigua (o sin clave)—, así que vuelve a generarla, guárdala y envía una tarea nueva; o bien (b) tu código de verificación reconstruye la cadena canónica de forma distinta a como lo hace hiapi. Registra los bytes exactos del cuerpo de la solicitud que recibió tu servidor y vuelve a ejecutar el HMAC sobre esos bytes exactos, sin ninguna re-serialización JSON intermedia.

taskId muestra success, pero no recibí la devolución de llamada ni una URL de resultado. Vuelve a solicitar GET /v1/tasks/{taskId} y revisa el array output. Las URL en output[*].url tienen caducidad (expireAt); descárgalas de inmediato. La entrega de la devolución de llamada y la vigencia de la URL son dos problemas independientes: incluso sin devolución de llamada, el endpoint GET es la fuente de verdad.

Vi la devolución de llamada en /en/dashboard/logs, pero mi servidor nunca la registró. Eso indica que el problema está en tu red perimetral, no en hiapi. Las causas habituales incluyen: reglas de CDN / WAF que bloquean solicitudes POST sin un User-Agent reconocible por tu equipo, una lista de IP permitidas en el cortafuegos, o un proxy inverso que reescribe la ruta. Permite ese POST entrante en tu cortafuegos y vuelve a ejecutar la prueba.

¿La URL de devolución de llamada consume el límite de tasa de mi cuenta? No. La devolución de llamada es una entrega que hiapi hace hacia ti y no está relacionada con tu presupuesto de tasa de POST /v1/tasks.