Use Case Webhooks

Practical Use Cases: Webhook Management¶

Webhooks are a core feature of the MindFlight AI Server, enabling real-time communication between external systems and your workflows. The server manages webhooks at two levels:

Incoming webhooks (from Providers).
Outgoing webhooks (to Clients).

1️⃣ Incoming Webhooks¶

What they do:
Incoming webhooks allow Providers to notify the server when something happens externally (like a new email).

Example:
The Unipile Provider defines a route:

/webhooks/unipile/notify

When Unipile receives a new email, it sends a POST request to this route with email data. MFO validates and processes it.

Metaphor:
It's like a doorbell: the Provider rings the bell to alert the server something has arrived.

2️⃣ Outgoing Webhooks¶

What they do:
Outgoing webhooks allow Clients to subscribe to events and receive push notifications when something happens internally.

Example:
A Client subscribes to the email.processed event via:

/api/notifications/subscribe

Whenever an email is processed, the server POSTs data to the Client's callback URL.

Metaphor:
This is like the restaurant calling you when your order is ready.

How Fiber Routes Are Mounted Dynamically¶

Each Provider can define its own HTTP routes. When the server starts:

The Provider's Init() function registers its webhook route.
The route is mounted dynamically in the Fiber app.

This allows you to plug in new Providers without modifying the core server code.

Example:
- Unipile registers /webhooks/unipile/notify. - Another Provider (e.g., Notion) might register /webhooks/notion/update.

Example Event Flow (Step-by-Step)¶

Here's what happens from start to finish when a webhook is received:

Step	Action
1️⃣	Incoming webhook: Provider sends a webhook to the server.
2️⃣	Event triggered: The server processes the webhook and fires an internal event (e.g., `email.received`).
3️⃣	Background job: A job is queued to handle the event (e.g., drafting a reply).
4️⃣	Outgoing webhook: Clients subscribed to the event receive a push notification.

Mermaid Diagram: Full Webhook Flow¶

sequenceDiagram
    participant Provider as Provider (Unipile)
    participant Server as MindFlight AI Server
    participant JobManager as Job Manager
    participant Client as Client App

    Provider->>Server: Send incoming webhook (/webhooks/unipile/notify)
    Server->>Server: Validate & parse webhook
    Server->>Server: Trigger event (unipile.email.received)
    Server->>JobManager: Queue background job (e.g., draft email)
    Server->>Client: Send outgoing webhook (email.processed)

Handling Retries and Errors¶

Webhook delivery can fail due to network issues or server downtime. The MindFlight AI Server includes basic retry logic:

✅ Incoming webhooks:
If the payload is invalid, the server responds with a 400 Bad Request.
If internal errors occur, the server logs the issue and returns 500 Internal Server Error.
✅ Outgoing webhooks:
The server retries failed notifications a set number of times (e.g., 3 retries with delays).
Failures are logged, and if the webhook still fails, it can trigger a manual alert or be retried later via CLI.

Best practice:

Always ensure your webhook endpoints are fast and reliable.
Implement idempotency in your webhook handlers to avoid duplicate processing.

Quick Recap¶

Webhook Type	What it does	Example Route
Incoming Webhook	Provider notifies the server of external events.	`/webhooks/unipile/notify`
Outgoing Webhook	Server pushes updates to Clients who subscribed to internal events.	Subscription via `/api/notifications/subscribe`

Metaphor Recap:

✅ Incoming webhook: Ringing the server's doorbell.
✅ Outgoing webhook: The server calling Clients when something is ready.