Webhooks

Los webhooks le permiten recibir notificaciones asíncronas cuando un proceso generativo se completa. En lugar de consultar manualmente el endpoint /api/v1/status/{id} para buscar actualizaciones, nuestro sistema envía la carga útil final directamente a su servidor tan pronto como el trabajo termina.

Cómo Usar Webhooks

Para usar webhooks con nuestra API, simplemente añada el parámetro webhook_url a su solicitud /run:

Cuando el proceso generativo finaliza (ya sea con éxito o si encuentra un error en tiempo de ejecución), nuestro despachador enviará una solicitud POST a su URL de webhook especificada, conteniendo la carga útil de estado completa.

Ejemplo: Uso de Webhooks con el Endpoint /run

fetch("https://fititon.app/api/v1/run?webhook_url=https://your-server.com/webhook", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
  },
  body: JSON.stringify({
    model_name: "product-to-model",
    inputs: {
      image: "http://example.com/path/to/garment.jpg",
      // ... other inputs
    }
  }),
});

Cargas Útiles de Webhook

La carga útil entregada a su URL de webhook es idéntica a la carga útil devuelta por el endpoint /v1/status/{id}. Contiene el estado final del trabajo.

Carga Útil de Éxito

Cuando el proceso se completa con éxito, su URL de webhook recibirá una solicitud POST con el status establecido en "success" y los resultados en el array output:

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1",
  "status": "success",
  "output": [
    "https://cdn.fititon.app/users/123/results/output_0.png"
  ],
  "error": null,
  "created_at": "2026-07-24T17:30:00.000Z",
  "updated_at": "2026-07-24T17:31:15.000Z"
}

Carga Útil de Error

Si el proceso falla debido a un error en tiempo de ejecución (por ejemplo, prenda no reconocible, filtros de moderación estrictos), su URL de webhook recibirá la cadena de error exacta.

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1",
  "status": "failed",
  "output": null,
  "error": {
    "name": "InputValidationError",
    "message": "The provided garment image could not be processed due to poor lighting."
  },
  "created_at": "2026-07-24T17:30:00.000Z",
  "updated_at": "2026-07-24T17:30:12.000Z"
}

Seguridad de Webhooks

Para asegurarse de que los webhooks que recibe realmente provienen de Fit It On y no han sido falsificados por un tercero malintencionado, debe implementar un mecanismo de verificación.

La forma más sencilla de asegurar sus webhooks es añadir un token secreto a la webhook_url que proporciona en su solicitud /v1/run.

Ejemplo: Uso de un Token Secreto

Cuando inicie un proceso generativo, añada una cadena altamente aleatoria a los parámetros de consulta de su URL:

// Asegúrese de codificar la URL del webhook si contiene parámetros de consulta.
const myWebhookUrl = encodeURIComponent("https://your-server.com/webhook?token=a8f9c2d1e5b47...");

fetch(`https://fititon.app/api/v1/run?webhook_url=${myWebhookUrl}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
  },
  // ...
  body: JSON.stringify({
    model_name: "product-to-model",
    inputs: {
      image: "http://example.com/path/to/garment.jpg",
    }
  }),
});

Cuando su servidor reciba la solicitud POST del webhook, simplemente verifique que el parámetro de consulta token coincida con su cadena secreta antes de procesar la carga útil JSON.

Entrega Garantizada y Reintentos

Nuestro sistema implementa un mecanismo de reintento de nivel empresarial para asegurar que nunca pierda una entrega de webhook, incluso si su servidor experimenta una interrupción temporal.

• Tiempo de Espera: Nuestro despachador impone un estricto tiempo de espera de 15 segundos. Su servidor debe reconocer el webhook con un código de estado HTTP 2xx en un plazo de 15 segundos. Si necesita realizar un procesamiento pesado (como descargar la imagen), debe responder al webhook primero y procesar los datos de forma asíncrona.
• Fallos: Si su servidor devuelve un código de estado que no sea 2xx (por ejemplo, 500 Internal Server Error), o no responde en 15 segundos, consideramos que la entrega ha fallado.
• Retroceso Exponencial: El sistema intentará hasta 5 reintentos utilizando retroceso exponencial (por ejemplo, reintentando en 5 minutos, 15 minutos, 45 minutos, etc.).

Si necesita saber qué intento de reintento está llegando actualmente a su servidor, puede inspeccionar el encabezado x-fititon-retry-count incluido en cada solicitud de webhook.

Mejores Prácticas

1. Implemente Idempotencia: Debido a las condiciones de la red y a nuestro mecanismo de reintento, es técnicamente posible que su servidor reciba el mismo webhook más de una vez. Debe usar el campo id para verificar si ya ha procesado el evento.
2. Responda Rápidamente: Siempre devuelva un estado 200 OK inmediatamente antes de descargar imágenes o actualizar bases de datos.
3. Siempre Verifique los Webhooks: Considere implementar un mecanismo de verificación (como el token URL secreto mencionado anteriormente) para asegurar que los webhooks provienen de nuestro servicio y evitar que actores malintencionados falsifiquen las cargas útiles.