Webhook Payload Reference

Webhook Delivery

When a prediction reaches a terminal state, each::labs fires off an HTTP POST to your configured webhook_url. Webhooks fire only on completion or failure — there are no webhooks for intermediate states, and cancellations do not trigger one.

Method: POST
Content-Type: application/json
Expected response: any 2xx status to acknowledge receipt; 4xx/5xx responses trigger a retry

Payload Structure

Webhook payloads use a compact two-value status vocabulary: succeeded or failed. This differs from the richer lifecycle you see when polling — use Get Prediction if you need the full six-state view (created, starting, processing, success, error, cancelled).

Prediction Succeeded

{
  "exec_id": "abc123-def456-ghi789",
  "flow_id": null,
  "status": "succeeded",
  "output": {
    "url": "https://storage.example.com/predictions/abc123/image.jpg"
  },
  "error": ""
}

exec_id — the prediction ID you received from Create Prediction
flow_id — the workflow ID when the prediction was triggered by a workflow, otherwise null
output — the prediction output; its shape depends on the model (string, array, or object)

Prediction Failed

{
  "exec_id": "abc123-def456-ghi789",
  "flow_id": null,
  "status": "failed",
  "output": [
    {
      "id": "",
      "status": "",
      "output": "",
      "error": "Error: Model timeout after 30s"
    }
  ],
  "error": ""
}

On failure, output is an array wrapping the error detail: read output[0].error for the failure reason. The top-level error field is always an empty string.

Webhook Handler Examples

from fastapi import FastAPI, Request

app = FastAPI()

@app.post("/webhooks/prediction")
async def handle_webhook(request: Request):
    payload = await request.json()

    if payload["status"] == "succeeded":
        output = payload["output"]
        print(f"Prediction complete: {output}")
        # Process the output...
    elif payload["status"] == "failed":
        detail = payload["output"][0]["error"] if payload["output"] else "unknown"
        print(f"Prediction failed: {detail}")

    return {"received": True}

app.post("/webhooks/prediction", (req, res) => {
  const payload = req.body;

  if (payload.status === "succeeded") {
    console.log(`Prediction complete: ${JSON.stringify(payload.output)}`);
    // Process the output...
  } else if (payload.status === "failed") {
    const detail = payload.output?.[0]?.error ?? "unknown";
    console.log(`Prediction failed: ${detail}`);
  }

  res.json({ received: true });
});

Security

Webhook Secret Verification

If you set a webhook_secret when creating your prediction, every delivery carries it verbatim in the X-Webhook-Secret header. Verify it with a constant-time string comparison:

import hmac

def verify_webhook(request_secret_header: str, secret: str) -> bool:
    return hmac.compare_digest(request_secret_header, secret)

The header carries the secret itself — no body signature is computed, so verification is a header comparison, not an HMAC of the payload.

Retry Behavior

Deliveries are attempted up to 3 times in total: the initial attempt plus 2 retries, spaced roughly 10 seconds apart. Retries stop after that. Use Get Webhook to check out the full delivery history.

Best Practices

Return 2xx as fast as you can, then process data asynchronously
Implement idempotency, since you may receive the same webhook more than once
Log incoming payloads for debugging
Use webhook_secret to verify payload authenticity
Set up monitoring for your webhook endpoint’s availability

Overview

Models

Predictions

Content Safety

Webhooks

OpenAPI Reference

Webhook Payload Reference

Webhook Delivery

Payload Structure

Prediction Succeeded

Prediction Failed

Webhook Handler Examples

Security

Webhook Secret Verification

Retry Behavior

Best Practices

​Webhook Delivery

​Payload Structure

​Prediction Succeeded

​Prediction Failed

​Webhook Handler Examples

​Security

​Webhook Secret Verification

​Retry Behavior

​Best Practices

Webhook Delivery

Payload Structure

Prediction Succeeded

Prediction Failed

Webhook Handler Examples

Security

Webhook Secret Verification

Retry Behavior

Best Practices