AGNT I/O

Inbound and outbound communication across every platform. I/O handles calendar webhooks from Google and Microsoft, outgoing webhook delivery to your systems, and the platform routing layer that makes Chats work across email, SMS, WhatsApp, Slack, Teams, and native chat.

Why AGNT I/O

Your agent needs to talk to the outside world — receive calendar events, deliver notifications to your backend, and route messages across platforms. Building this from scratch means writing webhook verification, retry logic, secret management, delivery logging, and platform-specific adapters.

AGNT I/O gives you all of it. Incoming webhooks from Google and Microsoft are verified and processed automatically. Outgoing webhooks deliver events to your HTTPS endpoints with configurable retries and signed payloads. Every delivery attempt is logged. Secrets are managed securely and can be rotated without downtime.

Quick Start

Configure an outgoing webhook to receive task completion events:

# Configure a webhook endpoint
curl -X PUT https://api.agnt.ai/account/webhook \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "url": "https://your-app.com/webhooks/agnt",
    "events": ["task.completed", "task.failed", "chat.processed"],
    "retryEnabled": true,
    "maxRetries": 3
  }'

# Test the webhook
curl -X POST https://api.agnt.ai/account/webhook/test \
  -H "Authorization: Bearer $TOKEN"

# Check delivery logs
curl "https://api.agnt.ai/account/webhook/logs?limit=10" \
  -H "Authorization: Bearer $TOKEN"

Core Concepts

Incoming Webhooks

Incoming webhooks let external services push events into AGNT. These are unauthenticated endpoints scoped to your account ID — the URL itself is the credential. Currently supported:

• Google Calendar: Calendar change notifications trigger sync operations.
• Microsoft Azure Calendar: Calendar change notifications with Microsoft's validation token handshake.

Both return 200 immediately and queue async processing via SQS. Your calendar data stays in sync without polling.

Outgoing Webhooks

Outgoing webhooks push events from AGNT to your systems. You configure one HTTPS endpoint per account and subscribe to specific event types. When a subscribed event occurs, AGNT delivers a signed payload to your URL.

Key behaviors:

• HTTPS required. No HTTP endpoints. No exceptions.
• Signed payloads. Every delivery includes a signature computed from your webhook secret. Verify it server-side to confirm authenticity.
• Configurable retries. Enable retries and set a max. Failed deliveries are retried with exponential backoff.
• Full delivery logging. Every attempt is recorded with status, response code, and timing. Query the logs to debug delivery issues.

Platform Routing

AGNT I/O is the layer that makes platform-aware messaging work. When a message arrives via email, SMS, WhatsApp, Slack, Teams, or native chat, the platform metadata is preserved and used to shape outbound responses. This routing happens transparently through the Chats API — you don't call I/O directly for message routing.

Supported Platforms

API Reference

Incoming Webhook Endpoints

These endpoints receive events from external services. They require no authentication — verification is handled through account-scoped URLs.

Google Calendar Webhook

POST https://api.agnt.ai/webhooks/:accountId/google/events

Receives Google Calendar push notifications. Returns 200 immediately and queues the sync operation.

# Google sends this automatically when calendar changes occur.
# You configure the callback URL in Google Calendar API settings:
# https://api.agnt.ai/webhooks/acct_abc123/google/events

// Response
200 OK

Azure Calendar Webhook

POST https://api.agnt.ai/webhooks/:accountId/azure/events

Receives Microsoft Calendar change notifications. Supports Azure's validation token flow — when Microsoft sends a validationToken query parameter, the endpoint echoes it back with text/plain content type.

# Microsoft sends validation request on subscription creation:
# POST /webhooks/acct_abc123/azure/events?validationToken=abc123
# Response: 200 OK, body: "abc123", Content-Type: text/plain

# Microsoft sends change notifications as POST with JSON body.
# Response: 202 Accepted

Outgoing Webhook Endpoints

All outgoing webhook endpoints require management-level authentication.

Webhook Object

{
  "enabled": true,
  "url": "https://your-app.com/webhooks/agnt",
  "events": ["task.completed", "task.failed", "chat.processed"],
  "hasSecret": true,
  "retryEnabled": true,
  "maxRetries": 3,
  "createdAt": "2026-03-01T10:00:00.000Z",
  "updatedAt": "2026-03-01T10:00:00.000Z"
}

Configure Webhook

PUT https://api.agnt.ai/account/webhook

curl -X PUT https://api.agnt.ai/account/webhook \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "url": "https://your-app.com/webhooks/agnt",
    "events": ["task.completed", "task.failed", "chat.processed"],
    "retryEnabled": true,
    "maxRetries": 5
  }'

{
  "enabled": true,
  "url": "https://your-app.com/webhooks/agnt",
  "events": ["task.completed", "task.failed", "chat.processed"],
  "hasSecret": true,
  "secret": "whsec_a1b2c3d4e5f6...",
  "retryEnabled": true,
  "maxRetries": 5,
  "createdAt": "2026-03-01T10:00:00.000Z",
  "updatedAt": "2026-03-01T10:00:00.000Z"
}

The secret field is only returned when the webhook is first created or regenerated. Store it securely — you won't see it again on subsequent GET requests.

Get Webhook Configuration

GET https://api.agnt.ai/account/webhook

curl https://api.agnt.ai/account/webhook \
  -H "Authorization: Bearer $TOKEN"

{
  "enabled": true,
  "url": "https://your-app.com/webhooks/agnt",
  "events": ["task.completed", "task.failed", "chat.processed"],
  "hasSecret": true,
  "retryEnabled": true,
  "maxRetries": 5,
  "createdAt": "2026-03-01T10:00:00.000Z",
  "updatedAt": "2026-03-01T10:00:00.000Z"
}

Remove Webhook

DELETE https://api.agnt.ai/account/webhook

Permanently removes the webhook configuration. Events will no longer be delivered.

curl -X DELETE https://api.agnt.ai/account/webhook \
  -H "Authorization: Bearer $TOKEN"

Send Test Event

POST https://api.agnt.ai/account/webhook/test

Sends a test payload to your configured webhook URL. Use this to verify your endpoint is receiving and processing events correctly.

curl -X POST https://api.agnt.ai/account/webhook/test \
  -H "Authorization: Bearer $TOKEN"

{
  "success": true,
  "statusCode": 200,
  "responseTime": 142
}

Reveal Webhook Secret

POST https://api.agnt.ai/account/webhook/reveal-secret

Returns the current webhook signing secret. This is a POST (not GET) because revealing a secret is an action, not a read.

curl -X POST https://api.agnt.ai/account/webhook/reveal-secret \
  -H "Authorization: Bearer $TOKEN"

{
  "secret": "whsec_a1b2c3d4e5f6..."
}

Regenerate Secret

POST https://api.agnt.ai/account/webhook/regenerate-secret

Generates a new signing secret. The old secret is immediately invalidated. Update your verification logic before or immediately after calling this.

curl -X POST https://api.agnt.ai/account/webhook/regenerate-secret \
  -H "Authorization: Bearer $TOKEN"

{
  "secret": "whsec_x9y8z7w6v5u4..."
}

Delivery Logs

GET https://api.agnt.ai/account/webhook/logs

curl "https://api.agnt.ai/account/webhook/logs?limit=5&success=false" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [
    {
      "id": "whl_001",
      "event": "task.completed",
      "url": "https://your-app.com/webhooks/agnt",
      "success": false,
      "statusCode": 500,
      "responseTime": 2300,
      "attempt": 2,
      "maxRetries": 5,
      "payload": {
        "event": "task.completed",
        "taskId": "task_abc123",
        "timestamp": "2026-03-01T10:02:30.000Z"
      },
      "createdAt": "2026-03-01T10:02:35.000Z"
    }
  ],
  "pagination": {
    "limit": 5,
    "offset": 0,
    "total": 1
  }
}

Incoming Webhook Events

GET https://api.agnt.ai/account/webhook/incoming

curl "https://api.agnt.ai/account/webhook/incoming?platform=google&limit=10" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [
    {
      "id": "whi_001",
      "type": "calendar.sync",
      "platform": "google",
      "action": "updated",
      "processed": true,
      "receivedAt": "2026-03-01T09:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 1
  }
}

For Coding Agents

If you're an AI coding agent integrating with AGNT I/O, here's what matters:

1. Verify webhook signatures. Every outgoing webhook delivery is signed with your secret. Compute the HMAC and compare before processing. Never skip this in production — unsigned payloads could be spoofed.

2. Return 200 quickly. Your webhook endpoint should acknowledge the delivery and process asynchronously. If your endpoint takes too long, the delivery will be marked as failed and retried (if retries are enabled). Keep response times under 5 seconds.

3. Handle retries idempotently. The same event can be delivered more than once if your endpoint returns a non-2xx status. Use the event ID or payload to deduplicate. Never assume exactly-once delivery.

4. Store the secret on creation. The secret field is only returned when the webhook is created or regenerated. It's not available on GET requests. Store it in your secrets manager immediately.

5. Use delivery logs to debug. If events aren't arriving, check GET /account/webhook/logs first. It shows every delivery attempt with status codes and timing. This is faster than guessing at network issues.

6. Don't poll for calendar changes. Configure the incoming webhook URLs in Google Calendar API and Microsoft Graph API settings. Calendar changes push to AGNT automatically. Polling is unnecessary and wasteful.

For Product Teams

AGNT I/O is the communication infrastructure layer. Here's how to think about it:

Webhooks replace polling. Instead of your application checking AGNT for updates every few seconds, AGNT pushes events to you in real time. Task completed? You know immediately. Chat processed? Instant notification. This is faster and cheaper than polling.

One endpoint, all events. You configure a single webhook URL and subscribe to the event types you care about. No need to set up separate endpoints for tasks, chats, and calendar events. Filter by event type in your handler.

Calendar sync is automatic. Once you connect Google or Microsoft calendars through Connect, change notifications flow through I/O automatically. Your agents always have current calendar data without any sync logic on your side.

Secret rotation is zero-downtime. When you regenerate a webhook secret, you get the new secret immediately. Update your verification logic, then old deliveries in flight will still verify against the old secret during the transition window. Plan your rotation accordingly.

Delivery reliability is visible. The webhook logs show every delivery attempt — successes, failures, retries, response times. When something breaks, you don't need to guess. The logs tell you exactly what happened and when.