Webhooks - TinyFish Web Agent

Webhooks let you receive an HTTP callback when a run reaches a terminal state, so you don’t need to poll for results.

How It Works

Pass a webhook_url when you create a run
When the run finishes (COMPLETED, FAILED, or CANCELLED), TinyFish sends a POST request to your URL
The payload contains the full run data — the same shape as GET /v1/runs/{id}

Webhook delivery is non-blocking. If your endpoint is down, the run still succeeds — you can always fetch the result via the API.

Configuration

Add webhook_url to any run creation endpoint. The URL must use HTTPS.

curl -X POST "https://agent.tinyfish.ai/v1/automation/run-async" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "goal": "Extract the page title",
    "webhook_url": "https://your-server.com/webhooks/tinyfish"
  }'

Webhooks are supported on all run endpoints: /run, /run-async, /run-sse, and /run-batch.

Payload

Your endpoint receives a POST request with Content-Type: application/json:

{
  "event": "run.completed",
  "run_id": "4562765d-156e-4c47-b217-55b3ec4a9720",
  "status": "COMPLETED",
  "data": {
    "run_id": "4562765d-156e-4c47-b217-55b3ec4a9720",
    "status": "COMPLETED",
    "goal": "Extract the page title",
    "created_at": "2026-03-25T10:30:00Z",
    "started_at": "2026-03-25T10:30:05Z",
    "finished_at": "2026-03-25T10:30:45Z",
    "num_of_steps": 3,
    "result": { "title": "Example Domain" },
    "error": null,
    "streaming_url": "https://tf-abc123.fra0-tinyfish.unikraft.app/stream/0",
    "browser_config": {
      "proxy_enabled": false,
      "proxy_country_code": null
    },
    "steps": [
      {
        "id": "09de224d-fb2b-45b7-b067-585726194a2e",
        "timestamp": "2026-03-25T10:30:05Z",
        "status": "COMPLETED",
        "action": "Navigate to https://example.com",
        "screenshot": null,
        "duration": "1.2s"
      }
    ]
  }
}

Minimal Example

A simplified view of the webhook payload with just the key fields:

{
  "event": "run.completed",
  "run_id": "run_abc123",
  "status": "COMPLETED",
  "data": {
    "started_at": "2026-01-15T10:30:00Z",
    "finished_at": "2026-01-15T10:30:45Z",
    "result": {
      "product_name": "Example Product",
      "price": 29.99
    },
    "error": null
  }
}

Event Types

Event	When
`run.completed`	Run finished (check `result` for data)
`run.failed`	Infrastructure error occurred
`run.cancelled`	Run was manually cancelled

Payload Fields

Field	Type	Description
`event`	string	Event type (e.g. `run.completed`)
`run_id`	string	Unique run identifier
`status`	string	`COMPLETED`, `FAILED`, or `CANCELLED`
`data`	object	Full run data — same shape as `GET /v1/runs/{id}`
`data.result`	object \| null	Extracted data (when completed)
`data.error`	object \| null	Error details (when failed)
`data.steps`	array	List of actions the agent took

Screenshots are not included in webhook payloads to keep the payload size small. To get screenshots, call GET /v1/runs/{id}?screenshots=base64 after receiving the webhook.

Error Payload

When a run fails, data.error contains details about what went wrong:

{
  "event": "run.failed",
  "run_id": "run-2",
  "status": "FAILED",
  "data": {
    "error": {
      "message": "Site blocked access",
      "category": "AGENT_FAILURE"
    },
    "result": null
  }
}

Retry Behavior

TinyFish retries failed webhook deliveries automatically:

Behavior	Detail
Total attempts	4 (1 initial + 3 retries)
Backoff	Exponential: 1s, 2s, 4s
Timeout	10 seconds per attempt
4xx responses	No retry (fails immediately)
5xx responses	Retried with backoff
Network errors	Retried with backoff

Receiving Webhooks

Here’s how to handle webhook events on your server:

import express from "express";

const app = express();
app.use(express.json());

app.post("/webhooks/tinyfish", (req, res) => {
  const { event, run_id, data } = req.body;

  switch (event) {
    case "run.completed":
      console.log(`Run ${run_id} completed:`, data.result);
      // Process the result
      break;
    case "run.failed":
      console.error(`Run ${run_id} failed:`, data.error?.message);
      // Handle the error
      break;
    case "run.cancelled":
      console.log(`Run ${run_id} was cancelled`);
      break;
  }

  // Respond quickly — TinyFish has a 10s timeout
  res.status(200).send("OK");
});

from flask import Flask, request

app = Flask(__name__)

@app.route("/webhooks/tinyfish", methods=["POST"])
def handle_webhook():
    payload = request.json
    event = payload["event"]
    run_id = payload["run_id"]
    data = payload["data"]

    if event == "run.completed":
        print(f"Run {run_id} completed:", data["result"])
        # Process the result
    elif event == "run.failed":
        print(f"Run {run_id} failed:", data.get("error", {}).get("message"))
        # Handle the error
    elif event == "run.cancelled":
        print(f"Run {run_id} was cancelled")

    # Respond quickly — TinyFish has a 10s timeout
    return "OK", 200

Best Practices

Respond within 10 seconds

TinyFish waits up to 10 seconds for your response. Do heavy processing asynchronously — acknowledge the webhook immediately and handle the data in the background.

Handle duplicates idempotently

In rare cases (network retries, server restarts), you may receive the same webhook more than once. Use run_id to deduplicate.

Verify by fetching the run

For sensitive workflows, confirm the webhook data by calling GET /v1/runs/{run_id} before acting on the payload.

Return 2xx to acknowledge

Any 2xx response acknowledges the webhook. Non-2xx responses trigger retries (except 4xx, which fail immediately).

Runs

Understand run lifecycle and statuses

Endpoints

Choose sync, async, or streaming

​How It Works

​Configuration

​Payload

​Minimal Example

​Event Types

​Payload Fields

​Error Payload

​Retry Behavior

​Receiving Webhooks

​Best Practices

​Related

Runs

Endpoints

How It Works

Configuration

Payload

Minimal Example

Event Types

Payload Fields

Error Payload

Retry Behavior

Receiving Webhooks

Best Practices

Related