Events Webhook

The events webhook lets your own systems — ticketing platforms, CRMs, internal services — trigger your agent. You POST an event, Apollo queues it, and the agent runs on it in the background.

Your system sends POST /messaging/v1/events with a JSON body.
Apollo validates the body, resolves the agent bound to your agent API key, and durably queues the event.
Apollo responds 202 Accepted with an event_id.

The agent runs asynchronously. A 202 confirms the event was queued — not that the agent has finished, or even started, processing it.

Send an event

cURL

curl -X POST "https://api-v3.aui.io/apollo-api/messaging/v1/events" \
  -H "Content-Type: application/json" \
  -H "x-agent-api-key: <agent_api_key>" \
  -d '{
    "thread_id": "ticket-11115",
    "agent_variables": {
      "ticket.id": "11115",
      "ticket.requester_email": "customer@example.com",
      "ticket.channel": "web",
      "ticket.human_has_replied": false
    }
  }'

POST `/messaging/v1/events`

Authentication

string

required

Your agent API key (sk-...). The key is bound to a single agent — events are always delivered to that agent, so the body never carries an agent id.

Keep the agent API key secret. Use it only from your servers, never in browsers or mobile apps, and rotate it if it is exposed.

Request body

Provide text, agent_variables, or both as the agent’s input.

string

The message to run the agent on. When omitted, the agent runs on agent_variables alone.

object

default:"{}"

Free-form key/value data passed to the agent as variables for this event. Values may be any JSON type.

string

Your own id for the conversation this event belongs to — any string from 1 to 255 characters. Reuse the same value to continue a conversation; omit it (or send a blank value) to start a new one. Unique per agent. Leading and trailing whitespace is trimmed.

Response

string

required

Unique id assigned to this event. Include it when contacting support.

{
  "event_id": "7d4f0c7e-2b0a-4a8e-9a57-3f1c2a6a9e11"
}

Conversations

thread_id groups events into a conversation. It is your own identifier — a ticket id, chat id, or order id — not one Apollo issues.

{
  "text": "A customer asked for a refund on order 10482.",
  "agent_variables": {
    "customer_email": "jane@example.com",
    "order_id": "10482"
  }
}

{
  "thread_id": "zendesk-ticket-88231",
  "text": "The customer replied with a photo of the damaged item."
}

Events that share a thread_id are processed in the order they were accepted.

Payload

Only text, agent_variables, and thread_id reach the agent. Any other top-level fields are accepted but ignored. That means you can point an existing third-party webhook at this URL without it being rejected — just put everything the agent needs inside agent_variables. The request body is limited to 1 MiB.

Errors

Failures use the standard error envelope. Branch on error.code and keep a default branch — the set may grow.

HTTP status	Code	When
`400`	`bad_request`	The request is malformed or missing required context.
`401`	`unauthorized`	The `x-agent-api-key` header is missing, or the key is invalid or revoked.
`403`	`forbidden`	The API key is not allowed to trigger this agent.
`404`	`not_found`	The agent bound to the API key no longer exists.
`404`	`webhooks.no_active_version`	The agent has no published version — publish one first.
`404`	`webhooks.no_runtime_version`	The agent’s active version must be republished before it can receive events.
`413`	`webhooks.payload_too_large`	The body exceeds the 1 MiB limit.
`422`	`validation_error`	The body is not valid JSON, or a field has the wrong type or length — see `details`.
`500`	`internal_error`	Unexpected server error. The event may not have been queued.
`502`	`upstream_unavailable`	The event could not be queued.
`503`	`internal_error`	Event ingestion is temporarily unavailable.

422

{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "request_id": "4f9a1c2e8b7d4e0f",
    "details": [
      { "field": "body.thread_id", "message": "String should have at most 255 characters" }
    ]
  }
}

Retries

502 and 503 responses mean the event was not queued. They are safe to retry with backoff. 4xx responses won’t succeed unchanged. Fix the request or the agent configuration before sending again.

Get started

Messaging

Management

Runtime v1

Events Webhook

Send an event

POST `/messaging/v1/events`

Authentication

Request body

Response

Conversations

Payload

Errors

Retries

​Send an event

​POST /messaging/v1/events

​Authentication

​Request body

​Response

​Conversations

​Payload

​Errors

​Retries

Send an event

POST `/messaging/v1/events`

Authentication

Request body

Response

Conversations

Payload

Errors

Retries