Webhooks

When you call the Chat endpoint with a webhook_url, the API operates in async mode: instead of holding the connection open while the agent processes, the API returns 202 Accepted immediately and sends the result to your webhook URL as soon as processing completes.

Use webhooks to avoid blocking your application while the AI thinks — ideal for n8n, Make, Zapier, or any backend that doesn’t want to deal with long-polling.

The async flow

1. You call POST /chat/{agentId} with webhook_url in the body (and optionally metadata).
2. The API responds immediately with 202 Accepted, returning conversation_id and message_id. The status is "processing".
3. When the agent finishes, the API sends a POST to your webhook_url with the full WebhookPayload.

curl -X POST https://api.squados.io/v1/chat/{agentId} \
  -H "Authorization: Bearer pk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is the status of order #1234?",
    "webhook_url": "https://your-app.com/webhooks/squados",
    "metadata": {
      "crm_ticket_id": "TKT-9981",
      "customer_email": "[email protected]"
    }
  }'

202 response:

{
  "success": true,
  "conversation_id": "conv_abc123",
  "message_id": "msg_xyz789",
  "status": "processing"
}

Webhook payload

When processing finishes, your endpoint receives a POST with the following schema:

Field	Type	Description
event	string	Event type: message.completed, message.received, or message.error
agent_id	uuid	ID of the agent that processed the message
conversation_id	uuid	Conversation ID (same as in the 202)
message_id	uuid	Message ID (same as in the 202)
response	string	The agent’s generated response. Present on message.completed
error	string	Error description. Present on message.error
model	string	LLM model used for generation
credits_used	number	Credits consumed by the processing
metadata	object	The metadata object you sent in the original request, echoed back intact
timestamp	date-time	When the event was generated (ISO 8601)

Example message.completed payload:

{
  "event": "message.completed",
  "agent_id": "agt_550e8400-e29b-41d4-a716-446655440000",
  "conversation_id": "conv_abc123",
  "message_id": "msg_xyz789",
  "response": "Order #1234 is being picked at the warehouse and is expected to ship tomorrow.",
  "model": "gpt-4o-mini",
  "credits_used": 3,
  "metadata": {
    "crm_ticket_id": "TKT-9981",
    "customer_email": "[email protected]"
  },
  "timestamp": "2026-06-08T14:32:07Z"
}

Possible events

Event	When it fires
message.completed	The agent finished generating the response successfully
message.received	The message was received and is queued (intermediate notification)
message.error	An error occurred during processing

Correlating with metadata

The metadata object you sent in the original request is echoed back intact in the webhook’s metadata field. Use this to match the agent’s response with the originating record in your system — support ticket, CRM lead, e-commerce order, anything.

Example: request with CRM metadata

curl -X POST https://api.squados.io/v1/chat/{agentId} \
  -H "Authorization: Bearer pk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Summarize this customer'\''s history.",
    "webhook_url": "https://your-app.com/webhooks/squados",
    "metadata": {
      "crm_ticket_id": "TKT-9981",
      "customer_email": "[email protected]"
    }
  }'

Webhook received:

{
  "event": "message.completed",
  "response": "The customer has made 3 purchases in the last 6 months, with no open complaints...",
  "metadata": {
    "crm_ticket_id": "TKT-9981",
    "customer_email": "[email protected]"
  },
  "timestamp": "2026-06-08T14:32:07Z"
}

Tip

Use metadata to pass any identifier from your system — ticket ID, CRM conversation ID, order ID, customer email. You receive exactly what you sent, without transformation, so any key that helps with routing in your handler is valid.

Responding to the webhook

Your endpoint must respond with a 2xx status (200, 201, or 204) right after receiving the payload — without heavy processing inside the handler. The API treats any non-2xx response as a delivery failure.

// Minimum accepted response (body can be empty)
HTTP/1.1 200 OK

Caution

Keep your webhook handler lean: receive, persist or enqueue, then respond 200 immediately. Heavy processing inside the handler can cause timeouts and the API may retry delivery.

For errors and API status codes, see the Errors reference.