Webhooks Overview

Webhooks allow your application to receive real-time HTTP notifications when events occur in your AgentPost organization. Instead of polling the API for changes, AgentPost pushes events to your endpoint as they happen -- enabling your AI agents to react instantly to incoming emails, delivery status updates, and domain changes.

How Webhooks Work

AgentPost's webhook system uses a reliable event delivery pipeline:

1. Event occurs -- An action happens in your organization (e.g., a new email arrives)
2. Event bus emits -- The internal event bus broadcasts the event
3. Queue enqueue -- A pg-boss job is created for each active webhook endpoint subscribed to the event type
4. HTTP delivery -- The webhook worker sends an HTTP POST request to your endpoint with the event payload
5. Retry on failure -- If delivery fails, AgentPost retries with exponential backoff

Event occurs -> Event Bus -> pg-boss Queue -> HTTP POST to your endpoint
                                  |
                                  +-> Retry with backoff on failure

Delivery Guarantees

AgentPost provides at-least-once delivery for webhooks. This means:

• Every event will be delivered to your endpoint at least once
• In rare cases (network issues, timeouts), an event may be delivered more than once
• Your endpoint should handle duplicate events gracefully using the event id field for deduplication

Retry Policy

When a delivery fails (non-2xx response or timeout), AgentPost retries with exponential backoff:

After 5 failed attempts, the delivery is marked as failed and no further retries occur for that specific event.

Auto-Disable Threshold

If an endpoint accumulates 50 consecutive delivery failures (across any events), AgentPost automatically disables the endpoint. This prevents wasting resources on endpoints that are consistently unreachable.

You can re-enable a disabled endpoint via the API once the underlying issue is resolved. Events that occurred while the endpoint was disabled are not retroactively delivered.

Event Payload Structure

Every webhook delivery sends a JSON payload with a common envelope format:

{
  "id": "evt_01JQ8X5K2M3N4P5R6S7T8V9W",
  "type": "message.received",
  "timestamp": "2026-03-08T14:30:00.000Z",
  "org_id": "org_01JQ8X5K2M3N4P5R6S7T8V9W",
  "env_id": "env_01JQ8X5K2M3N4P5R6S7T8V9W",
  "data": {
    // Event-specific payload
  }
}

Endpoint Management

You can manage webhook endpoints through the API:

import AgentPost from '@agentpost/sdk';

const client = new AgentPost({ apiKey: 'ap_sk_live_your_key_here' });

// Create a webhook endpoint
const endpoint = await client.webhookEndpoints.create({
  url: 'https://your-app.com/webhooks/agentpost',
  events: ['message.received', 'message.bounced'],
  description: 'Production webhook receiver',
});

console.log(endpoint.secret); // whsec_... (shown only on creation)

from agentpost import AgentPost

client = AgentPost(api_key="ap_sk_live_your_key_here")

# Create a webhook endpoint
endpoint = client.webhook_endpoints.create(
    url="https://your-app.com/webhooks/agentpost",
    events=["message.received", "message.bounced"],
    description="Production webhook receiver",
)

print(endpoint.secret)  # whsec_... (shown only on creation)

curl -X POST https://api.agent-post.dev/api/v1/webhooks/endpoints \
  -H "Authorization: Bearer ap_sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/agentpost",
    "events": ["message.received", "message.bounced"],
    "description": "Production webhook receiver"
  }'

Webhooks vs WebSockets

AgentPost offers both webhooks and WebSockets for real-time events. Choose based on your use case:

For AI agent backends, webhooks are typically the best choice. For user-facing dashboards showing real-time email activity, consider WebSockets.

Next Steps

• Events Reference -- See all available event types and their payloads
• Setup Guide -- Step-by-step guide to receiving webhook events
• Verifying Webhooks -- Secure your endpoint with signature verification