Webhooks

Overview

Webhooks are primarily used by the Channels service to receive inbound messages and delivery-lifecycle callbacks from the email provider. When a webhook is received, Ergon records the activity and emits a platform event (such as channels.email.received) that the central Automations service can react to.

Event Type Catalog

Every action across the platform emits a structured event. These events power the Event Streams API, real-time WebSocket feeds, and internal processing pipelines. Browse the complete event and automation-trigger catalog for every payload shape and compatible predicate, or download the machine-readable JSON. The table below highlights common event types.

Event Envelope

Every platform event follows a standard envelope structure. The payload field contains event-type-specific data.

{
  "id": "e1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "event_type": "workflows.items.created",
  "source": "workflows",
  "company_id": "c0ffee00-cafe-babe-dead-beefcafebabe",
  "actor_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "actor_type": "member",
  "correlation_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "timestamp": "2026-04-14T10:30:00Z",
  "payload": {
    "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
    "item_id": "660e8400-e29b-41d4-a716-446655440000",
    "phase_id": "770e8400-e29b-41d4-a716-446655440000",
    "title": "New customer request"
  }
}

Email Inbound Webhook

The email inbound webhook receives events from Resend when emails arrive at configured addresses. The webhook URL is registered automatically when you create a channel config and verify the domain.

Example inbound email payload from Resend:

{
  "type": "email.received",
  "data": {
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Help with my order",
    "text": "I need help with order #12345...",
    "html": "<p>I need help with order #12345...</p>",
    "headers": {
      "message-id": "<[email protected]>",
      "in-reply-to": "<[email protected]>"
    }
  }
}

Trigger Actions

Reacting to inbound events is handled by the central Automations service rather than by the webhook endpoint itself. You author rules that match a trigger event (for example channels.email.received) and run one or more actions. Common actions include:

• Invoke an AI agent with the received message as input.
• Create or route a workflow item from the message.
• Send an outbound email or an outbound webhook.

Security

Webhook endpoints implement the following security measures:

• Provider signature verification (webhook signing)
• Address matching — only emails to configured addresses are processed
• Recursion safeguards in the Automations service to prevent runaway loops
• Rate limiting on the webhook endpoint