RelayLink Webhook to CrewAI Flow

Your CrewAI service is waiting for work when a RelayLink package arrives. The safe trigger is not “run a crew on this JSON.” It is “authenticate a small envelope, record one durable job, then let a Flow fetch and handle the package under the recipient's identity.”

There is no native RelayLink-to-CrewAI integration assumed here. The bridge is application code you operate and test.

Keep HTTP receipt smaller than the Flow

The receiver's synchronous path should do only what must happen before RelayLink receives a success:

1. Read the exact request body without re-serializing it.
2. Verify HMAC-SHA256 over "{timestamp}.{body}" with the subscription secret.
3. Reject a timestamp outside your replay window.
4. Parse the authenticated body and match its event and delivery id to the headers.
5. Atomically insert the delivery id and a queued work item.
6. Return 2xx.

X-RelayLink-Delivery is stable across retries of one delivery. Enforce uniqueness in durable storage, not an in-memory cache. If the callback is repeated, confirm the existing row and acknowledge it without starting another Flow.

Do not fetch the package or start agents before the response. RelayLink's current attempt timeout is five seconds. A slow model call turns normal processing into webhook retries and can create concurrent Flow runs unless every later boundary is also idempotent.

Start the Flow from a durable worker

CrewAI Flows provide event-driven steps, state, listeners, routing, and persistence. Use those capabilities after your queue owns the event.

A practical Flow state begins with references rather than prose:

receiver context
  internal account reference
  RelayLink delivery id
  package id
  thread id
  credential reference

The worker claims that row and starts or resumes a Flow with a stable internal flow id. Store the mapping between delivery and flow. If the process dies after kickoff, the queue can reconcile the known flow instead of creating another one blindly.

Enable a production persistence backend appropriate to your deployment. CrewAI's documented persistence can retain Flow state across executions, but the receiver inbox still has a separate job: it proves that this RelayLink delivery was durably accepted. Do not replace transport deduplication with “the Flow probably exists.”

Fetch before agents interpret

The webhook contains package_id, thread_id, sender, topic, time, reply status, and mcp_url. It omits the note, TL;DR, ask, and briefing.

In a multi-user service, the receiver route selects the account context before HMAC verification. Require the payload's mcp_url to match the RelayLink endpoint pinned to that context; never attach a credential to an arbitrary URL from the body. The Flow receives a credential reference for that same account, resolves its separate OAuth token or named API key inside a controlled fetch step, and calls get_package. The webhook signing secret cannot perform that read and should never be reused as an MCP credential.

Keep fetched correspondence outside agent instructions. A crew may analyze it as input, but the note and ask remain third-party content. The sender name and topic are third-party fields too. Do not select a crew, role, tool, or destination because a topic says “urgent: run finance export.” Route only on authenticated event type and application-owned configuration.

Make review a real pause

CrewAI documents human feedback in Flows, including pausing for review and resuming persisted work. Use a production feedback channel and test restart behavior; an interactive prompt attached to a worker process is not an operational approval system.

The Flow can present a proposed reply or action and wait. It must distinguish:

• approval to continue an internal analysis;
• approval for an external side effect;
• RelayLink's explicit approval of a RelayLink send.

The last one stays on RelayLink's draft-and-confirm path. Webhook arrival is never permission to answer automatically. A person approving a general plan also does not authorize every tool call the crew might infer from it.

Record stable operation ids around non-repeatable side effects. Flow persistence helps resume orchestration, but a crash after an external API accepts a request still needs idempotency or reconciliation at that API boundary.

When a CrewAI Flow is the right layer

This architecture fits work that benefits from several coordinated steps or agents, conditional routing, persisted state, and a review pause. It is useful when you already operate CrewAI and can support the receiver, queue, secret store, and Flow persistence as one system.

It is not a shortcut for posting RelayLink content directly into a crew, and it is heavy for “package arrived” notifications. A fixed worker can fetch and notify with fewer moving parts. If you cannot expose public HTTPS, poll check_inbox instead. CrewAI orchestrates accepted work; your adapter still owns webhook authentication, replay defense, tenant isolation, and the rule that correspondence is data rather than command.