# Event webhooks

> Get a signed POST on your own endpoint when something happens on your FlyMyAI account, first when a connected account stops working.

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](https://docs.flymy.ai/agents/guides/webhook-triggers.md).

> **Note: 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

| 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:

```json
{
  "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

```python
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

```bash
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](https://www.standardwebhooks.com/):

- `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:

```python
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:

```python
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'})`):

```js
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](https://flymy.ai/blog/oauth-token-expired-webhooks/).
