Your self-hosted agent should react when a package arrives, but nothing is calling it. Leaving a timer to ask every few seconds works, yet most of those requests answer the same way: there is nothing waiting.
An AI agent webhook reverses who starts the exchange. The service that knows an event happened sends an HTTP POST to a receiver you control. That receiver verifies the request and schedules the agent workflow. In practical terms, the webhook wakes the workflow.
What the webhook actually does
A webhook is a trigger delivered over HTTP. It normally has four parts:
- A public HTTPS endpoint that can receive a POST
- An event name saying what happened
- An identifier that makes retries safe to recognize
- A signature that proves the body came from someone holding the receiver's secret
The endpoint is not the agent itself. It is a small front door: verify, record, return a success status, then hand work to a queue or worker. That separation matters because a callback has a short response budget while an agent may take much longer to reason, fetch context, or wait for a model.
If the receiver process is not running, the webhook cannot revive the machine by magic. It wakes a workflow only when an internet-reachable service is there to accept it.
How that differs from an MCP call
An MCP connection is agent-initiated. The agent connects to a server, discovers tools, and calls one. Each call is a request for data or an action.
A webhook is service-initiated. RelayLink calls your URL because a package was delivered. The callback tells your system that work may be waiting; it does not replace the MCP tool call that reads that work.
RelayLink keeps this boundary especially clear. Its webhook includes a package_id and an mcp_url. After verifying the callback, the agent authenticates to that MCP address and calls get_package. The webhook provides timing. MCP provides authenticated access to the briefing.
How that differs from polling
Polling means the agent starts on a schedule and calls check_inbox, whether or not anything changed. It needs no inbound endpoint, so it suits a process behind a firewall or a machine that only makes outbound connections.
A webhook sends a request only when there is an event. That can reduce idle calls and start work sooner, but it adds an internet-facing receiver, signature verification, retry deduplication, and operational monitoring.
The two approaches can coexist. Use webhooks for the fast path and a slower check_inbox schedule as reconciliation. A missed or abandoned callback then delays the workflow instead of hiding a package indefinitely.
RelayLink sends an envelope, not the briefing
The package.received payload names the delivery, package, thread, sender, topic, time, reply state, and MCP address. It never contains the note, TL;DR, ask, or context brief.
That omission gives the webhook limited authority. Someone who obtained the signing secret could forge envelope metadata and provoke fetch attempts, so the secret still matters. They could not substitute a briefing or read one without the worker's separate MCP authorization. The receiver should treat sender and topic fields as untrusted metadata, never as instructions.
Fetching through get_package also preserves a precise delivery trail. A successful webhook POST proves that a machine accepted an envelope. It does not prove that an assistant fetched or read the package.
When an agent webhook fits
Choose a webhook when you operate an always-available public receiver and want event-driven starts. Choose polling when inbound hosting is undesirable, or when a scheduled process is already part of the system. For many self-hosted agents, a resilient design uses both: a signed trigger for speed, an authenticated MCP fetch for content, and occasional polling for recovery.
RelayLink webhook registration is portal-only at /account/webhooks. The setup guide covers the receiver, one-time signing secret, and test event.