> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guppyapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Events (Webhooks)

> Listen for state changes and execution updates

Guppy is **event‑driven**. All state changes are emitted as events. We recommend setting up webhooks to stay in sync with intent progress.

## Debugging / Polling (v1)

During the v1 migration phase, Guppy also exposes an **events timeline** endpoint to fetch recorded events for a specific intent (useful for debugging and dashboards):

`GET /intents/{intent_id}/events`

Query params:

* `limit` (default 50, max 200)
* `cursor` (optional; use the returned `next_cursor`)

Response:

```json theme={null}
{
  "request_id": "req_...",
  "intent_id": "int_...",
  "events": [
    {
      "event_id": "evt_...",
      "type": "intent.created",
      "timestamp": "2026-01-18T21:10:00Z",
      "data": {}
    }
  ],
  "next_cursor": null
}
```

### Event Types

* `intent.created`: Intent has been successfully recorded.
* `intent.waiting`: Conditions are not yet met (e.g., out of stock).
* `intent.executing`: Guppy has started the execution flow.
* `execution.step_started`: A specific action in the plan has started.
* `execution.step_failed`: A step failed but may be retried.
* `execution.needs_user_action`: Input (3DS, OTP) is required to proceed.
* `intent.succeeded`: Intent goal has been achieved.
* `intent.failed`: Intent has reached a terminal failure state.

### Event Payload

```json theme={null}
{
  "event_id": "evt_123",
  "type": "intent.succeeded",
  "intent_id": "int_789",
  "timestamp": "2026-01-12T02:14:55Z",
  "data": {
    "merchant": "target",
    "total_charged_cents": 79999,
    "currency": "USD"
  }
}
```