Webhooks

Webhooks allow you to receive asynchronous notifications when a generative process completes. Instead of manually polling the /api/v1/status/{id} endpoint to check for updates, our system pushes the final payload directly to your server as soon as the job is finished.

How to Use Webhooks

To use webhooks with our API, simply append the webhook_url parameter to your /run request:

When the generative process finishes (either successfully or if it encounters a runtime error), our dispatcher will send a POST request to your specified webhook URL containing the complete status payload.

Example: Using Webhooks with the /run Endpoint

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
    }
  }),
});

Webhook Payloads

The payload delivered to your webhook URL is identical to the payload returned by the /v1/status/{id} endpoint. It contains the final state of the job.

Success Payload

When the process completes successfully, your webhook URL will receive a POST request with the status set to "success" and the results in the output array:

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

Error Payload

If the process fails due to a runtime error (e.g., unrecognizable garment, strict moderation filters), your webhook URL will receive the exact error string.

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

Webhook Security

To ensure that the webhooks you receive actually originate from Fit It On and aren't forged by a malicious third party, you should implement a verification mechanism.

The simplest way to secure your webhooks is to append a secret token to the webhook_url you provide in your /v1/run request.

Example: Using a Secret Token

When you start a generative process, append a highly random string to your URL query parameters:

// 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",
    }
  }),
});

When your server receives the webhook POST request, simply verify that the token query parameter matches your secret string before processing the JSON payload.

Guaranteed Delivery & Retries

Our system implements an enterprise-grade retry mechanism to ensure you never miss a webhook delivery, even if your server experiences temporary downtime.

• Timeout: Our dispatcher enforces a strict 15-second timeout. Your server must acknowledge the webhook with a 2xx HTTP status code within 15 seconds. If you need to perform heavy processing (like downloading the image), you should respond to the webhook first, and process the data asynchronously.
• Failures: If your server returns a non-2xx status code (e.g., 500 Internal Server Error), or fails to respond within 15 seconds, we consider the delivery failed.
• Exponential Backoff: The system will attempt up to 5 retries using exponential backoff (e.g., retrying in 5 minutes, 15 minutes, 45 minutes, etc.).

If you need to know which retry attempt is currently hitting your server, you can inspect the x-fititon-retry-count header included in every webhook request.

Best Practices

1. Implement Idempotency: Because of network conditions and our retry mechanism, it is technically possible for your server to receive the same webhook more than once. You should use the id field to check if you have already processed the event.
2. Respond Quickly: Always return a 200 OK status immediately before downloading images or updating databases.
3. Always Verify Webhooks: Consider implementing a verification mechanism (like the secret URL token mentioned above) to ensure webhooks are coming from our service and prevent malicious actors from spoofing payloads.