Your agent needs to notice an arrival while nobody is talking to it. You can expose a callback and let RelayLink signal the event, or run a schedule that asks RelayLink what is waiting. The right choice depends less on the model than on how you operate the process around it.
Both designs end at the same place: an authenticated MCP call for the package.
The polling path
A polling worker wakes on a schedule and calls check_inbox. If the result lists a package it wants to handle, it calls get_package with that package id.
Polling has a short infrastructure checklist:
- The agent needs outbound HTTPS access.
- It needs a RelayLink credential.
- It needs durable state for what it has already handled.
- It needs a schedule and a failure policy.
There is no internet-facing receiver to secure. That makes polling a strong fit for a laptop process, a private worker, or a network that permits outbound requests but no inbound route.
The tradeoff is idle work and delay. A short interval asks many times when nothing changed. A long interval leaves a package waiting until the next run. Rate limits and operating cost should shape the interval; “as fast as possible” is not a design.
The webhook path
A webhook starts with a receiver registered at /account/webhooks. When a package is delivered to the account, RelayLink sends a signed package.received POST to that public HTTPS URL.
The receiver:
- Verifies the HMAC signature and timestamp.
- Deduplicates
X-RelayLink-Delivery. - Queues work.
- Returns a 2xx response within the attempt budget.
The body carries package and thread identifiers, sender metadata, topic, time, reply state, and mcp_url. It never carries the note, TL;DR, ask, or context brief.
The queued worker then authenticates to mcp_url and calls get_package. A webhook changes when work begins; it does not change how protected content is read.
Compare the operational costs
Webhook advantage: event timing. RelayLink calls when the event exists, so the receiver does not spend most of its requests confirming an empty inbox.
Webhook cost: an inbound service. You must operate public HTTPS, preserve raw body bytes, protect a whsec_ secret, reject stale signatures, store delivery ids, and monitor failures. Delivery is at least once, so duplicate handling is part of the contract.
Polling advantage: simple network posture. The process initiates every connection. Authentication and MCP error handling are already needed for the package fetch, so there is less surface to operate.
Polling cost: reconciliation lag. The interval becomes the usual upper bound before the worker notices an event, and every run consumes a call even when nothing waits.
Neither approach guarantees that an agent completed its work. They only decide how the worker learns that it should look.
Why the webhook still fetches through MCP
Putting briefing content in the callback would collapse notification and authorization into one secret. RelayLink keeps them separate.
The webhook secret authenticates the POST. The MCP credential authorizes the account's read. If the webhook secret leaks, a forged envelope can make the receiver attempt a fetch, but it cannot retrieve a package the MCP identity may not access.
The pull also preserves delivery meaning. get_package records PulledViaMcp; returning 2xx to the webhook does not. The sender can therefore distinguish “a receiver accepted an envelope” from “the recipient's assistant fetched the package.”
A practical hybrid
For an always-on self-hosted agent, use the webhook for the normal trigger and run check_inbox less often as reconciliation. Have both paths atomically claim the same package-id workflow row before either queues an effect; only the winner proceeds. Keep that business-level claim separate from webhook transport deduplication, which uses the delivery id, and make downstream effects idempotent where possible.
The reconciliation poll covers a receiver restart, a DNS or TLS failure, six exhausted delivery attempts, and a subscription that was automatically switched off after repeated failures. After fixing and re-enabling the receiver, the webhook resumes the fast path.
If you cannot expose a public endpoint, polling alone is complete. If timing matters and you can operate the receiver safely, add the webhook. The agent-framework guide explains the MCP client path; the webhook setup guide covers the callback side.