Webhooks

Webhooks permitem que você receba notificações assíncronas quando um processo generativo é concluído. Em vez de consultar manualmente o endpoint /api/v1/status/{id} para verificar atualizações, nosso sistema envia o payload final diretamente para o seu servidor assim que o trabalho é finalizado.

Como Usar Webhooks

Para usar webhooks com nossa API, basta adicionar o parâmetro webhook_url à sua requisição /run:

Quando o processo generativo for concluído (seja com sucesso ou se encontrar um erro de tempo de execução), nosso despachante enviará uma requisição POST para a URL do seu webhook especificada, contendo o payload de status completo.

Exemplo: Usando Webhooks com o 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
    }
  }),
});

Payloads de Webhook

O payload entregue à sua URL de webhook é idêntico ao payload retornado pelo endpoint /v1/status/{id}. Ele contém o estado final do trabalho.

Payload de Sucesso

Quando o processo for concluído com sucesso, sua URL de webhook receberá uma requisição POST com o status definido como "success" e os resultados no 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"
}

Payload de Erro

Se o processo falhar devido a um erro de tempo de execução (por exemplo, peça de vestuário irreconhecível, filtros de moderação rigorosos), sua URL de webhook receberá a string de erro exata.

{
  "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"
}

Segurança do Webhook

Para garantir que os webhooks que você recebe realmente se originam do Fit It On e não são forjados por terceiros maliciosos, você deve implementar um mecanismo de verificação.

A maneira mais simples de proteger seus webhooks é adicionar um token secreto à webhook_url que você fornece em sua requisição /v1/run.

Exemplo: Usando um Token Secreto

Ao iniciar um processo generativo, adicione uma string altamente aleatória aos parâmetros de consulta da sua URL:

// Make sure to URL-encode the webhook URL if it contains query parameters!
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",
    }
  }),
});

Quando seu servidor receber a requisição POST do webhook, basta verificar se o parâmetro de consulta token corresponde à sua string secreta antes de processar o payload JSON.

Entrega Garantida e Retentativas

Nosso sistema implementa um mecanismo de retentativa de nível empresarial para garantir que você nunca perca uma entrega de webhook, mesmo que seu servidor experimente tempo de inatividade temporário.

• Tempo Limite: Nosso despachante impõe um tempo limite estrito de 15 segundos. Seu servidor deve reconhecer o webhook com um código de status HTTP 2xx dentro de 15 segundos. Se você precisar realizar processamento pesado (como baixar a imagem), você deve responder ao webhook primeiro e processar os dados assincronamente.
• Falhas: Se o seu servidor retornar um código de status diferente de 2xx (por exemplo, 500 Internal Server Error), ou falhar em responder dentro de 15 segundos, consideramos a entrega falha.
• Backoff Exponencial: O sistema tentará até 5 retentativas usando backoff exponencial (por exemplo, retentando em 5 minutos, 15 minutos, 45 minutos, etc.).

Se você precisar saber qual tentativa de retentativa está atualmente atingindo seu servidor, você pode inspecionar o cabeçalho x-fititon-retry-count incluído em cada requisição de webhook.

Melhores Práticas

1. Implemente Idempotência: Devido às condições de rede e ao nosso mecanismo de retentativa, é tecnicamente possível que seu servidor receba o mesmo webhook mais de uma vez. Você deve usar o campo id para verificar se já processou o evento.
2. Responda Rapidamente: Sempre retorne um status 200 OK imediatamente antes de baixar imagens ou atualizar bancos de dados.
3. Sempre Verifique os Webhooks: Considere implementar um mecanismo de verificação (como o token de URL secreto mencionado acima) para garantir que os webhooks estão vindo do nosso serviço e evitar que atores maliciosos falsifiquem payloads.