Event webhooks
FlyMyAI can tell your own systems when something happens on your account. Subscribe a
public https:// endpoint to event types, and each event arrives as one signed POST,
the way Composio sends connected_account.expired. The first event type is
connection.expired: a connected account stopped working and must be reconnected.
This page covers events FlyMyAI sends out. To start an agent from events you send in, see Webhook Triggers v1.
Event webhooks are live in the app (Developers > Webhooks), in the REST API, in the
Agents MCP (the webhook tools in tools/list) and in the Python SDK from flymyai
1.2.0rc29 (python -m pip install 'flymyai>=1.2.0rc29', then client.webhooks).
Events
| Type | When | data |
|---|---|---|
connection.expired | A connected account stopped accepting FlyMyAI's access: its grant expired or was revoked. Its owner gets an email with a Reconnect button at the same moment. At most once a day per connection. | connection (id, kind: connection or custom_mcp_server, toolkit, alias, name, status: reconnect_required), reconnect_url, agents (up to five names of agents that use it) |
webhook.test | You asked for a test event. | message, webhook_id |
Every request body is one compact JSON object:
{
"id": "4c1f9a52-7d0e-4b8a-9f3c-2a6e5d1b7c90",
"type": "connection.expired",
"created_at": "2026-11-17T08:00:02+00:00",
"schema": "flymy.webhooks.v1",
"data": {
"connection": {
"id": "9a8b7c6d-1111-4222-8333-444455556666",
"kind": "connection",
"toolkit": "sentry",
"alias": "default",
"name": "Sentry",
"status": "reconnect_required"
},
"reconnect_url": "https://app.flymy.ai/mcp-configs#sentry?connection_id=9a8b7c6d-1111-4222-8333-444455556666",
"agents": ["Daily error digest"]
}
}
Send the user to reconnect_url: signing in there again issues a fresh grant, and the
agents that use the connection work again. New event types are added to the same
flymy.webhooks.v1 schema; an existing data shape does not change within v1.
Create a webhook
In the app
Open Developers > Webhooks at https://app.flymy.ai/developers/webhooks and add a
webhook: its https:// address, the events and an optional description. The page shows
the signing secret once, with a Copy button; store it where your receiver reads it.
From a webhook's row you can send a test event and watch its deliveries (status,
attempts, HTTP code), pause and resume it, rotate its secret or delete it. In a team
workspace the page manages the team's webhooks, which receive the team's events.
Python SDK
import os
from flymyai import AgentClient
client = AgentClient(api_key=os.environ["FLYMYAI_API_KEY"])
created = client.webhooks.create(
"https://example.com/flymyai/events",
events=["connection.expired"],
description="Reconnect alerts",
idempotency_key="webhook-reconnect-alerts",
)
signing_secret = created.secret # whsec_..., shown once: store it for your receiver
client.webhooks.send_test(created.webhook.id) # one webhook.test event
for delivery in client.webhooks.list_deliveries(created.webhook.id):
print(delivery.event_type, delivery.status, delivery.last_status_code)
The async client has the same methods with await. update(webhook_id, url=..., events=..., description=..., is_active=False) changes or pauses a webhook,
delete(webhook_id) removes it and rotate_secret(webhook_id) replaces the secret at
once. A refused URL, event or field raises InvalidWebhookError (field names it);
past 10 webhooks, WebhookLimitError.
REST
curl -X POST https://backend.flymy.ai/api/v1/agents/webhooks/ \
-H "X-API-KEY: $FLYMYAI_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: webhook-reconnect-alerts" \
-d '{"url": "https://example.com/flymyai/events", "events": ["connection.expired"], "description": "Reconnect alerts"}'
It answers 201 with {"schema": "flymy.webhooks.v1", "webhook": {...}, "secret": "whsec_..."}. Authenticate with X-API-KEY, the Agents MCP OAuth bearer or your app
session.
| Method and path | What it does |
|---|---|
GET /api/v1/agents/webhooks/ | Your webhooks and event_types (each type with its description) |
POST /api/v1/agents/webhooks/ | Create: url, events, optional description; the answer has the secret, once |
GET /api/v1/agents/webhooks/{id}/ | One webhook |
PATCH /api/v1/agents/webhooks/{id}/ | Change url, events or description, or pause with is_active: false |
DELETE /api/v1/agents/webhooks/{id}/ | Delete it (204) |
POST /api/v1/agents/webhooks/{id}/test/ | Queue one webhook.test event (202) |
POST /api/v1/agents/webhooks/{id}/rotate-secret/ | A new secret at once; the old one stops verifying |
GET /api/v1/agents/webhooks/{id}/deliveries/ | The 50 newest deliveries of the last 30 days |
A webhook answers id, url, events, description, is_active, created_at,
last_delivery_at, last_delivery_status and consecutive_failures, never its
secret. Writes take an optional Idempotency-Key: a retry with the same key and body
changes nothing twice, and a replayed create or rotate answers secret: null (the
secret is shown once; rotate it if it was lost). The same key with another body answers
409 idempotency_conflict.
Refusals: 400 invalid_webhook with field (url must be a public https:// address,
events must come from event_types, description has at most 200 characters),
409 webhook_limit (at most 10 webhooks per account), 404 for a webhook of another
account.
From your AI assistant
The Agents MCP has list_webhooks, create_webhook, update_webhook,
delete_webhook, test_webhook, rotate_webhook_secret and
list_webhook_deliveries. Ask, for example: "Send a webhook to
https://example.com/flymyai/events when one of my connections stops working, then send
a test event."
Verify a delivery
Each request carries three headers, as in Standard Webhooks:
webhook-id: the delivery's id. It stays the same on every retry: use it to skip a repeat.webhook-timestamp: Unix seconds of this attempt.webhook-signature:v1,and the Base64 HMAC-SHA256 of<webhook-id>.<webhook-timestamp>.<raw body>, keyed with the Base64-decoded part of the secret afterwhsec_. Several space-separated signatures may appear; one match is enough.
Verify the raw body before you parse it, refuse a timestamp more than five minutes from
now and compare in constant time. Answer 400 to a request that fails.
With the Python SDK:
import os
from flymyai import WebhookSignatureError, verify_webhook
def receive(body: bytes, headers) -> int:
try:
event = verify_webhook(body, headers, os.environ["FLYMYAI_WEBHOOK_SECRET"])
except WebhookSignatureError:
return 400
if event.type == "connection.expired":
notify(event.data["connection"]["name"], event.data["reconnect_url"])
return 204
With the Python standard library:
import base64
import hashlib
import hmac
import json
import time
def verify(body: bytes, headers, secret: str) -> dict:
message_id = headers["webhook-id"]
timestamp = headers["webhook-timestamp"]
if abs(time.time() - int(timestamp)) > 300:
raise ValueError("stale delivery")
key = base64.b64decode(secret.split("_", 1)[1])
signed = f"{message_id}.{timestamp}.".encode() + body
expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
given = [s.split(",", 1)[1] for s in headers["webhook-signature"].split() if s.startswith("v1,")]
if not any(hmac.compare_digest(expected, signature) for signature in given):
raise ValueError("bad signature")
return json.loads(body)
With Node.js (read the raw body, for example with express.raw({type: 'application/json'})):
import crypto from 'node:crypto';
export function verify(rawBody, headers, secret) {
const id = headers['webhook-id'];
const timestamp = headers['webhook-timestamp'];
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) throw new Error('stale delivery');
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
const expected = crypto.createHmac('sha256', key).update(`${id}.${timestamp}.`).update(rawBody).digest();
const ok = headers['webhook-signature'].split(' ').some((entry) => {
const [version, value] = entry.split(',');
if (version !== 'v1' || !value) return false;
const given = Buffer.from(value, 'base64');
return given.length === expected.length && crypto.timingSafeEqual(given, expected);
});
if (!ok) throw new Error('bad signature');
return JSON.parse(rawBody.toString('utf8'));
}
The Standard Webhooks libraries verify these deliveries too, with the whsec_ secret.
Delivery and retries
- Answer any
2xxwithin 30 seconds; do slow work after you answer. - Network errors,
408,429and5xxare retried: the pause doubles from 30 seconds up to an hour, eight retries over about two hours. Any other answer, a redirect included, ends the delivery asfailed. - A delivery can arrive more than once: skip a
webhook-idyou have already handled. - Only public
https://addresses receive events; redirects are not followed. - Each webhook shows
last_delivery_at,last_delivery_statusandconsecutive_failures; deliveries are kept for 30 days. - A paused webhook (
is_active: false) receives nothing until you resume it; events in between are not replayed.
For why OAuth connections expire and how teams handle it, see the blog post OAuth token expired: catch dead AI agent connections with a webhook.