Skip to main content

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.

Availability

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​

TypeWhendata
connection.expiredA 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.testYou 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 pathWhat 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 after whsec_. 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 2xx within 30 seconds; do slow work after you answer.
  • Network errors, 408, 429 and 5xx are 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 as failed.
  • A delivery can arrive more than once: skip a webhook-id you have already handled.
  • Only public https:// addresses receive events; redirects are not followed.
  • Each webhook shows last_delivery_at, last_delivery_status and consecutive_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.