Webhooks

All API endpoints support an optional async mode. Instead of waiting for the response, provide a webhook_url and receive results via an HTTP POST when processing completes.

When to Use Webhooks

• Long-running requests where you don’t want to hold a connection open
• Fire-and-forget workflows where you process results in a separate service
• Queue-based architectures where a webhook handler feeds results into your pipeline

How It Works

1. Add a webhook_url parameter to any API request
2. The API validates your request, consumes credits, and returns 201 Accepted immediately
3. Processing happens in the background
4. When complete, the API sends an HTTP POST to your webhook URL with the results

Immediate Response

When webhook_url is provided, the API returns a 201 response immediately:

{
  "success": true,
  "async": true,
  "message": "Request accepted. Results will be delivered to the provided webhook URL."
}

Webhook Delivery Payload

Success

The webhook payload uses the same response format as synchronous requests, with an additional api field identifying which API produced the result.

For APIs that return binary data, the result is base64-encoded:

{
  "success": true,
  "api": "image_generation",
  "data": {
    "buffer": "<base64-encoded-binary>",
    "mime_type": "image/png"
  }
}

For APIs that return structured data, the extracted fields are returned directly:

{
  "success": true,
  "api": "document_extraction",
  "data": {
    "invoice_number": {
      "value": "INV-2024-001",
      "confidence": 0.95,
      "source": "Invoice Number: INV-2024-001"
    }
  }
}

Failure

If processing fails, the webhook receives an error payload:

{
  "success": false,
  "api": "image_generation",
  "error": {
    "message": "layers must be a non-empty list"
  }
}

Requirements

• HTTPS only — The webhook_url must use https://. HTTP URLs are rejected with a 400 error.
• Return 2xx — Your webhook endpoint must return a 2xx status code to acknowledge receipt.

Retry Behavior

Processing and delivery are handled separately:

• Processing is attempted once. If it fails, an error payload is delivered to your webhook and credits are refunded (same as a synchronous 5xx error).
• Delivery is retried up to 3 times if your webhook endpoint returns a non-2xx response or is unreachable.

Delivery retries do not re-run processing — only the HTTP POST is retried.

Credits

Credits are consumed when the request is accepted (same as synchronous requests). If processing fails with a server error, credits are automatically refunded.

Credits are not refunded when processing completed successfully but webhook delivery to your endpoint fails. Ensure your webhook endpoint is reliable and returns 2xx to acknowledge receipt.

Example

curl -X POST https://api.iterationlayer.com/image-generation/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://your-server.com/webhook",
    "dimensions": { "width": 800, "height": 600 },
    "layers": [
      { "index": 0, "type": "solid-color-background", "hex_color": "#FFFFFF" }
    ],
    "output_format": "png"
  }'

import { IterationLayer } from "iterationlayer";
const client = new IterationLayer({ apiKey: "YOUR_API_KEY" });

// Returns immediately with 201
const result = await client.generateImageAsync({
  webhook_url: "https://your-server.com/webhook",
  dimensions: { width_in_px: 800, height_in_px: 600 },
  layers: [
    { index: 0, type: "solid-color-background", hex_color: "#FFFFFF" },
  ],
  output_format: "png",
});
console.log(result.message); // "Request accepted..."

from iterationlayer import IterationLayer
client = IterationLayer(api_key="YOUR_API_KEY")

# Returns immediately with 201
result = client.generate_image_async(
    webhook_url="https://your-server.com/webhook",
    dimensions={"width_in_px": 800, "height_in_px": 600},
    layers=[
        {"index": 0, "type": "solid-color-background", "hex_color": "#FFFFFF"},
    ],
    output_format="png",
)

import il "github.com/iterationlayer/sdk-go"
client := il.NewClient("YOUR_API_KEY")

// Returns immediately with 201
result, err := client.GenerateImageAsync(il.GenerateImageAsyncRequest{
    WebhookURL:   "https://your-server.com/webhook",
    Dimensions:   il.Dimensions{WidthInPx: 800, HeightInPx: 600},
    OutputFormat: "png",
    Layers: []il.Layer{
        il.NewSolidColorBackgroundLayer(0, "#FFFFFF"),
    },
})
fmt.Println(result.Message) // "Request accepted..."