Webhooks

Overview

Provide a webhook_url when triggering a workflow to receive an HTTP POST with execution results when it completes (successfully or with an error). Add a webhook_secret to have each delivery signed so you can verify it came from each::labs.

Setting Up

Include webhook_url in your trigger request, and webhook_secret to receive signed deliveries:

curl -X POST https://api.eachlabs.ai/v1/workflows/trigger/WF_ID/v1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "inputs": {"prompt": "A sunset landscape"},
    "webhook_url": "https://your-app.com/webhooks/workflow-completed",
    "webhook_secret": "whsec_your_secret_key"
  }'

Webhook Request

Method: POST
Content-Type: application/json
Body: Same structure as Get Execution response

Signature headers

When the trigger included a webhook_secret, the delivery also carries:

Header	Meaning
`X-Webhook-Signature`	`sha256=` plus a lowercase hex HMAC-SHA256 over `<X-Webhook-Timestamp>.<raw request body>`
`X-Webhook-Timestamp`	Unix time in seconds at which the delivery was signed

Verify the signature over the raw request body — see Verifying Webhook Signatures.

Payload Examples

Successful Execution

{
  "execution_id": "69ae8c7b-7500-4a45-b7c0-348b8cc2665b",
  "workflow_id": "50741f40-8621-4d46-8a91-dff4d873be98",
  "status": "completed",
  "started_at": "2025-12-04T11:48:10Z",
  "inputs": {
    "prompt": "A sunset landscape"
  },
  "step_outputs": {
    "step1": {
      "step_id": "step1",
      "status": "completed",
      "output": "A breathtaking panoramic view...",
      "primary": "A breathtaking panoramic view...",
      "metadata": {
        "model": "openai-chatgpt-5"
      }
    },
    "step2": {
      "step_id": "step2",
      "status": "completed",
      "output": ["https://storage.googleapis.com/uploads/image.png"],
      "primary": "https://storage.googleapis.com/uploads/image.png",
      "metadata": {
        "model": "flux-1-1-pro"
      }
    }
  },
  "output": ["https://storage.googleapis.com/uploads/image.png"]
}

Failed Execution

{
  "execution_id": "69ae8c7b-7500-4a45-b7c0-348b8cc2665b",
  "workflow_id": "50741f40-8621-4d46-8a91-dff4d873be98",
  "status": "failed",
  "started_at": "2025-12-04T11:48:10Z",
  "inputs": {
    "prompt": "A sunset landscape"
  },
  "error": "ExecutionFailed",
  "error_cause": "Step 'generate_image' failed: Model timeout after 30s"
}

Bulk Trigger Webhook

When triggered via bulk-trigger, the payload includes bulk_id:

{
  "execution_id": "exec-1",
  "workflow_id": "50741f40-8621-4d46-8a91-dff4d873be98",
  "bulk_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "output": ["https://storage.googleapis.com/uploads/image.png"]
}

Each execution in a bulk operation sends its own webhook notification.

Handler Examples

from fastapi import FastAPI, Request

app = FastAPI()

@app.post("/webhooks/workflow-completed")
async def handle_workflow_webhook(request: Request):
    execution = await request.json()

    if execution["status"] == "completed":
        final_output = execution["output"]
        step_details = execution["step_outputs"]
        print(f"Workflow completed: {final_output}")
    elif execution["status"] == "failed":
        error = execution.get("error_cause", "Unknown error")
        print(f"Workflow failed: {error}")

    return {"received": True}

app.post("/webhooks/workflow-completed", (req, res) => {
  const execution = req.body;

  if (execution.status === "completed") {
    console.log(`Workflow completed: ${execution.output}`);
    // Process step_outputs if needed
  } else if (execution.status === "failed") {
    console.error(`Workflow failed: ${execution.error_cause}`);
  }

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

Retry Behavior

Deliveries are attempted up to 3 times in total: the initial attempt plus 2 retries, spaced roughly 10 seconds apart. Every attempt carries the same signature and timestamp. Your endpoint should return a 200 OK to acknowledge receipt.

Best Practices

Return 200 OK immediately, process data asynchronously
Implement idempotency using execution_id as a deduplication key
Handle both completed and failed statuses
For bulk operations, correlate webhooks using bulk_id
Set a webhook_secret and verify the signature before trusting a payload

Overview

Concepts

API Reference

OpenAPI Reference

Examples

Webhooks

Overview

Setting Up

Webhook Request

Signature headers

Payload Examples

Successful Execution

Failed Execution

Bulk Trigger Webhook

Handler Examples

Retry Behavior

Best Practices

​Overview

​Setting Up

​Webhook Request

​Signature headers

​Payload Examples

​Successful Execution

​Failed Execution

​Bulk Trigger Webhook

​Handler Examples

​Retry Behavior

​Best Practices

Overview

Setting Up

Webhook Request

Signature headers

Payload Examples

Successful Execution

Failed Execution

Bulk Trigger Webhook

Handler Examples

Retry Behavior

Best Practices