Webhook Setup

Webhooks connect MailAfrica’s inbound email to your agent. When an email arrives, MailAfrica sends an HTTP POST to your webhook endpoint.

Endpoint

The webhook receiver is part of the webhook server:

uv run mailafrica-agent webhook

This starts a FastAPI server on the configured host and port (default: 0.0.0.0:8000).

Available Endpoints

Setting Up a Webhook

Step 1: Start the Webhook Server

uv run mailafrica-agent webhook

For production, use Docker or systemd — see Deployment.

Step 2: Create a Webhook on MailAfrica

Use the MCP tool or the MailAfrica dashboard:

create_webhook(
    address_id=1,
    url="https://agent.mailafrica.online/webhooks/mailafrica",
    secret="your_webhook_secret"
)

The secret should match your AGENT_WEBHOOK_SECRET environment variable.

Step 3: Verify It Works

Send a test ping:

test_webhook(webhook_id=1)

Check your server logs to confirm the ping was received and the HMAC signature verified.

Webhook Payload

MailAfrica sends a POST request with this structure:

{
  "event": "inbound.message_received",
  "data": {
    "message_id": 123,
    "address_id": 1,
    "from": "sender@example.com",
    "subject": "Hello",
    "received_at": "2024-01-15T10:30:00Z"
  }
}

HMAC Verification

Every webhook request includes an X-Webhook-Signature header containing an HMAC-SHA256 signature. The agent verifies this signature against your AGENT_WEBHOOK_SECRET before processing.

If verification fails, the request is rejected with a 401 status code.

Security

• Always use HTTPS in production
• Keep AGENT_WEBHOOK_SECRET secure and unique
• The webhook endpoint returns 200 OK immediately and processes in the background
• Invalid signatures are rejected with 401

Chat Endpoints

The webhook server also exposes AI chat endpoints:

POST /chat

{
  "messages": [
    {"role": "user", "content": "How do I send an email?"}
  ]
}

Returns an AI-generated response using the agent’s support knowledge base.

POST /v1/support/chat

Same as /chat, provided as a standard API endpoint path.