Skip to main content
Planned Feature — Coming Soon

🚧 This feature is not yet released. The documentation below describes planned behavior and may change before launch.

Webhooks & Events

Get notified when agent runs complete instead of polling. Webhooks deliver results to your server the moment a run finishes.

Setting Up Webhooks​

Register a Webhook Endpoint​

from flymyai import AgentClient

client = AgentClient(api_key="fly-***")

webhook = client.webhooks.create(
    url="https://your-server.com/webhooks/flymy",
    events=["run.completed", "run.failed"],
    secret="your-webhook-secret"
)

Supported Events​

EventDescription
run.completedAgent run finished successfully
run.failedAgent run failed with an error

Webhook Payload​

When a run completes, FlyMy.AI sends a POST request to your URL:

{
  "event": "run.completed",
  "timestamp": "2025-01-15T10:00:15Z",
  "data": {
    "run_id": "run_xyz789",
    "agent_id": "agent_abc123",
    "agent_name": "Sales Lead Profiler",
    "status": "done",
    "duration_ms": 14200,
    "input": {
      "name": "Dana Lee",
      "company": "Acme Robotics"
    },
    "output": {
      "background": "VP of Engineering at Acme Robotics...",
      "buying_triggers": ["Scaling team", "New product launch"],
      "outreach_angle": "Focus on engineering productivity tools..."
    }
  }
}

Failed Run Payload​

{
  "event": "run.failed",
  "timestamp": "2025-01-15T10:00:15Z",
  "data": {
    "run_id": "run_xyz790",
    "agent_id": "agent_abc123",
    "status": "error",
    "error": {
      "type": "tool_error",
      "message": "web_search returned no results for query"
    }
  }
}

Handling Webhooks​

Python (Flask)​

from flask import Flask, request, jsonify
import hmac
import hashlib

app = Flask(__name__)
WEBHOOK_SECRET = "your-webhook-secret"

@app.route("/webhooks/flymy", methods=["POST"])
def handle_webhook():
    # Verify signature
    signature = request.headers.get("X-FlyMyAI-Signature")
    payload = request.get_data()
    expected = hmac.new(WEBHOOK_SECRET.encode(), payload, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(signature, expected):
        return jsonify({"error": "Invalid signature"}), 401

    event = request.json

    if event["event"] == "run.completed":
        run_data = event["data"]
        print(f"Run {run_data['run_id']} completed!")
        print(f"Output: {run_data['output']}")
        # Process the results...

    elif event["event"] == "run.failed":
        run_data = event["data"]
        print(f"Run {run_data['run_id']} failed: {run_data['error']['message']}")
        # Handle the error...

    return jsonify({"received": True}), 200

JavaScript (Express)​

import express from "express";
import crypto from "crypto";

const app = express();
const WEBHOOK_SECRET = "your-webhook-secret";

app.post("/webhooks/flymy", express.json(), (req, res) => {
    // Verify signature
    const signature = req.headers["x-flymyai-signature"];
    const payload = JSON.stringify(req.body);
    const expected = crypto.createHmac("sha256", WEBHOOK_SECRET).update(payload).digest("hex");

    if (signature !== expected) {
        return res.status(401).json({ error: "Invalid signature" });
    }

    const event = req.body;

    if (event.event === "run.completed") {
        console.log(`Run ${event.data.run_id} completed!`);
        console.log("Output:", event.data.output);
    }

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

app.listen(3000);

Fire-and-Forget Pattern​

Start runs without waiting — let webhooks deliver results:

# Start multiple runs and move on
for lead in leads:
    client.runs.create(
        agent_id="your-username/lead-profiler",
        input={"name": lead["name"], "company": lead["company"]}
    )

# Your webhook handler processes results as they arrive
# No need to poll or wait

Use with Marketplace Agents​

If you're running someone else's marketplace agent programmatically, webhooks save you from polling:

# Register webhook once
webhook = client.webhooks.create(
    url="https://your-server.com/webhooks/flymy",
    events=["run.completed"]
)

# Fire off runs to marketplace agents
run = client.runs.create(
    agent_id="creator/seo-auditor",
    input={"url": "https://mysite.com"}
)
# Result arrives at your webhook endpoint

Managing Webhooks​

# List webhooks
webhooks = client.webhooks.list()

# Update endpoint
client.webhooks.update(
    webhook_id=webhook.id,
    url="https://new-server.com/webhooks/flymy"
)

# Delete webhook
client.webhooks.delete(webhook_id=webhook.id)

Next Steps​