Skip to main content

​
Overview

The Webhook transport provides HTTP-based asynchronous messaging, perfect for web services and microservice architectures. It uses standard HTTP POST requests for communication without requiring cloud provider dependencies.
Webhook transport uses HTTP POST requests where the client sends requests to server endpoints and provides a webhook URL for receiving async responses.

​
Examples

View complete working examples in the GitHub repository:

​
Quick Start

​
Basic Usage

# Server (FastAPI)
from asyncmcp.webhook import WebhookSessionManager
from fastapi import FastAPI, Request

app = FastAPI()
manager = WebhookSessionManager(mcp_app)

@app.post("/mcp/request")
async def handle_request(request: Request):
    return await manager.handle_request(request)

# Client
from asyncmcp.webhook import webhook_client
from asyncmcp import WebhookClientConfig

config = WebhookClientConfig(
    server_url="https://api.example.com/mcp/request"
)

async with webhook_client(config, webhook_path="/webhook") as client:
    async with ClientSession(client.read, client.write) as session:
        # Webhook URL provided automatically in initialize
        await session.initialize()

​
Configuration

​
Server Configuration

Class: WebhookServerConfig
​
timeout_seconds
float
default:"30.0"
HTTP timeout for sending webhooks to clients.
​
max_retries
int
default:"0"
Number of retry attempts for failed webhook deliveries (default: no retries).
​
transport_timeout_seconds
float
Optional overall transport timeout.

​
Client Configuration

Class: WebhookClientConfig
​
server_url
string
default:"http://localhost:8000/mcp/request"
URL of the server’s HTTP endpoint.Example: https://api.example.com/mcp/request
​
timeout_seconds
float
default:"30.0"
HTTP request timeout in seconds.
​
max_retries
int
default:"0"
Number of retry attempts for failed requests (default: no retries).
​
client_id
string
Unique client identifier. Auto-generated if not provided.
​
transport_timeout_seconds
float
Optional overall transport timeout.
Note: The webhook URL is provided via the _meta field in the initialize request and is handled automatically by the client.
⌘I