Webhooks

Webhooks allow you to receive asynchronous notifications when a process completes. Instead of polling an endpoint to check the status, webhooks push updates directly to your specified URL.

How to Use Webhooks

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

POST https://api.fashn.ai/v1/run?webhook_url=https://your-server.com/webhook

When the process completes, our system will send a POST request to your specified webhook URL with the complete response payload.

Webhook Retry Mechanism

Our system implements a robust retry mechanism to ensure webhook delivery:

• If a webhook delivery fails (non-2xx response), we automatically retry
• The system attempts up to 5 retries
• Retries occur within a timespan of approximately 5 minutes

Example: Using Webhooks with the /run Endpoint

Based on the /run endpoint from the FASHN API, here's how to implement webhooks:

// Request to start a process with webhook notification
fetch('https://api.fashn.ai/v1/run?webhook_url=https://your-server.com/webhook', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer YOUR_API_KEY',
  },
  body: JSON.stringify({
    // Your request payload
  }),
});

Success Webhook Payload

When the process completes successfuly, your webhook URL will receive a POST request with a payload similar to:

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1",
  "status": "completed",
  "output": [
    "https://cdn.staging.fashn.ai/123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1/output_0.png"
  ],
  "error": null
}

Error Webhook Payload

When the process has failed, your webhook URL will receive a POST request with a payload similar to:

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1-u1",
  "status": "failed",
  "error": {
    "name": "ImageLoadError",
    "message": "Error loading model image: The URL's Content-Type is not an image. Content-Type: text/plain;charset=UTF-8"
  }
}

Best Practices

1. Implement Idempotency: Your webhook handler should be idempotent to handle potential duplicate deliveries.
2. Respond Quickly: Your webhook endpoint should respond with a 2xx status code as quickly as possible. Process the webhook data asynchronously if needed.
3. Verify Webhooks: Consider implementing a verification mechanism to ensure webhooks are coming from our service.
4. Monitor Webhook Failures: Set up monitoring for webhook failures to detect any issues with your endpoint.

Troubleshooting

If you're not receiving webhook notifications:

• Verify your webhook URL is publicly accessible
• Check that your server responds with a 2xx status code
• Test your webhook endpoint with a tool like Webhook.site

For additional support, contact our team at support@fashn.ai.