Skip to main content
Kapso agents emit webhook events so you can track their execution lifecycle.

Execution created

agent.execution.createdFired when a new agent execution starts.

Execution updated

agent.execution.updatedFired whenever an execution advances (node transition, tool result, etc.).

Execution completed

agent.execution.completedFired when an agent finishes successfully.

Execution failed

agent.execution.failedFired when an execution fails (timeout, tool failure, runtime error).

​
Headers

Agent webhooks include the same headers as WhatsApp webhooks: 
X-Webhook-Event: agent.execution.created
X-Webhook-Signature: <hmac-hex-signature>
X-Idempotency-Key: <unique-key-per-event>
Content-Type: application/json

​
Sample payload

{
  "id": "exec_123",
  "type": "agent.execution.completed",
  "timestamp": "2025-10-05T12:00:00Z",
  "agent": {
    "id": "agent_456",
    "name": "Support AI"
  },
  "customer": {
    "id": "cus_789",
    "external_customer_id": "acme-123"
  },
  "conversation": {
    "id": "convo_123",
    "channel": "whatsapp"
  },
  "status": "completed",
  "results": {
    "final_message": "Thanks! Your order has been updated.",
    "variables": {
      "order_id": "ORDER-9876"
    }
  }
}

​
Best practices

  • Store X-Idempotency-Key to avoid processing duplicate events.
  • Verify the HMAC signature before trusting the payload.
  • Return a 2xx HTTP status quickly; heavy processing should be done asynchronously.
  • Use separate endpoints for agent vs WhatsApp webhooks for observability.
⌘I