5. Webhook Novita y procesamiento asíncrono

Actualizado: 20 de febrero de 2026.

Este capítulo resuelve el punto crítico de producción: cómo cerrar tareas asíncronas y persistir el resultado final.

Prerrequisitos

1. Tener clonado o disponible codigo/ de esta serie.
2. Contar con Firebase y Novita configurados para pruebas.
3. Haber completado el capítulo anterior del curso.

Paso 1: Endpoint webhook

Archivo clave:

• codigo/backend/InvitaIA.Api/Controllers/NovitaWebhookController.cs

Responsabilidades:

1. Aceptar payload de Novita.
2. Soportar forma payload o data.
3. Ignorar eventos que no sean ASYNC_TASK_RESULT.
4. Extraer task_id, status y URLs.

Paso 2: Worker de aplicación

Archivo clave:

• codigo/backend/InvitaIA.Api/Workers/NovitaTaskWorker.cs

Responsabilidades:

1. Buscar invitación por taskId.
2. Descargar imagen/video de Novita.
3. Subir archivo a Firebase Storage.
4. Guardar previewUrl, finalUrl, status en Firestore.

Paso 3: Flujo completo

sequenceDiagram
    participant API as .NET API
    participant NOV as Novita AI
    participant WH as /api/webhooks/novita
    participant WRK as NovitaTaskWorker
    participant FS as Firestore/Storage

    API->>NOV: Start async generation
    NOV-->>API: task_id
    NOV->>WH: ASYNC_TASK_RESULT
    WH->>WRK: HandleWebhookAsync(taskId, status, urls)
    WRK->>FS: upload + save status/finalUrl

Paso 4: Polling de respaldo

Además del webhook, existe PendingInvitationWorker como red de seguridad para tareas en QUEUED o PROCESSING.

Paso 5: Comprobación manual

cd codigo/backend
rg -n "api/webhooks/novita|HandleWebhookAsync|task-result" InvitaIA.Api -S

Troubleshooting

1. No llega webhook: backend no accesible públicamente.
2. Webhook llega pero no actualiza invitación: taskId no coincide.
3. Status se queda en processing: valida parseo de status en webhook y GetTaskAsync.

FAQ corta

¿Webhook y polling son redundantes?

No. Polling actúa como fallback en fallos de red o retries perdidos.

¿Dónde se sube el archivo final?

En Firebase Storage vía IFirebaseService.UploadFileAsync.

¿Qué estado marca éxito?

TASK_STATUS_SUCCEED y equivalentes normalizados.

Fuente verificada

• Código del curso:
  • codigo/backend/InvitaIA.Api/Controllers/NovitaWebhookController.cs
  • codigo/backend/InvitaIA.Api/Workers/NovitaTaskWorker.cs
  • codigo/backend/InvitaIA.Api/Workers/PendingInvitationWorker.cs
• Documentación oficial Novita:
  • Novita API webhook
  • Novita API task result