Introduction

Our webhook system provides real-time notifications about the status of your media generation tasks. This guide explains how webhooks work in our system and how to handle webhook notifications effectively.

How Webhooks Work

When you create a media generation request, you can specify a webhook URL that will receive updates about the status of your task. The system will automatically send POST requests to your webhook URL at key points in the media generation process.

Webhook Flow

When creating a media request, include your webhook URL in your API request body along with your other parameters. The webhook URL should be a publicly accessible endpoint on your server that can receive POST requests.

await fetch('https://api.artificialstudio.ai/api/generate', {
   method: 'POST',
   headers: {
     'Content-Type': 'application/json',
     'Authorization': 'YOUR_API_KEY'
   },
   body: {
     model: "playground-v2",
     input: {
       prompt: "Astronaut in a jungle, cold color palette, muted colors, detailed, 8k"
     },
     webhook: "https://your-server.com/api/webhook"
   }
});

As your media generation task progresses, our system will send webhook notifications to your specified URL with the current status and relevant information.

Webhook Payload

When a webhook is triggered, you'll receive a JSON payload containing the following information:

• id: The unique identifier of the media.
• status: Current status of the media generation (pending, uploading, processing, success, error).
• output: URL of the generated media (when successful).
• model: The model slug used for generation.
• type: Type of media (image, video, audio, text, object).
• payload: Original request parameters.
• error: Error message (if any).

Retry Mechanism

Our webhook system includes a robust retry mechanism to ensure reliable delivery of notifications:

1. Initial attempt occurs immediately after status change.
2. If delivery fails, the system will retry with increasing intervals:
   • 5 seconds
   • 15 seconds
   • 1 minute
   • 5 minutes
   • 15 minutes
   • 1 hour
   • 6 hours
   • 12 hours
   • 24 hours
3. The system will continue retrying until either:
   • A successful delivery (HTTP 200 response).
   • All retry attempts are exhausted.

Implementation Example

To handle webhook notifications, you'll need to set up an endpoint on your server that can:

1. Receive POST requests.

2. Parse the JSON payload.

3. Process the webhook data according to your needs.

4. Return a 200 status code to acknowledge receipt.

   app.post("/api/webhook", (req: any, res: any) => {
   
       const { id, status, output, model, type, payload, error } = req.body;
   
       res.send("Webhook received");
   
   });
   

Best Practices

• Quick Response: Your webhook endpoint should respond quickly (within 5 seconds).
• Idempotency: Handle duplicate webhooks gracefully, as retries might cause multiple deliveries.
• Verification: Implement security measures to verify webhook authenticity.
• Logging: Maintain logs of received webhooks for debugging purposes.

Error Handling

The webhook system considers a delivery successful only when receiving an HTTP 200 response. Any other response code or connection error will trigger the retry mechanism.

Common Error Scenarios

• Timeout (endpoint takes too long to respond).
• Network errors.
• Non-200 HTTP response codes.

Conclusion

Our webhook system provides a reliable way to receive real-time updates about your media generation tasks. By following these guidelines and implementing proper error handling, you can ensure robust integration with our service.

For additional support or questions about webhook implementation, please contact our support team or refer to our API documentation.