> ## Documentation Index
> Fetch the complete documentation index at: https://crevio.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Events & Event Sources (event-triggered tasks)
> Make your AI workforce reactive — fire Tasks automatically when something happens. Learn internal Events, event_conditions, and third-party Event Sources, and how they differ from webhooks.
**Events make your [Tasks](/docs/developer/guides/tasks) reactive: instead of running on a clock, an event-triggered task fires the moment something happens.** A buyer pays, a form is submitted, a connected app reports a change — and the agent goes to work. Crevio recognizes two kinds of triggers: **internal Events** (things that happen inside your Crevio account) and **Event Sources** (things that happen in third-party apps you connect). Both drive Tasks with `trigger_type: event`.
## Three things that sound alike — keep them straight
| Concept | Direction | What it does |
| ------------------------------------------ | ---------------------------- | ----------------------------------------------------------------------------------------------- |
| **Events** | Crevio → your agent | Internal signals that **trigger Tasks** to run inside Crevio. |
| **Event Sources** | Third-party app → your agent | A connected app's events that **trigger Tasks**, so external activity can drive your workforce. |
| **[Webhooks](/docs/developer/guides/webhooks)** | Crevio → your server | HTTP notifications pushed to **your own backend** so your code can react. |
The rule of thumb: **Events and Event Sources trigger Crevio's AI; webhooks notify your code.** The two systems share an event vocabulary (e.g. `order.paid` exists in both) but do different jobs — and you can use both for the same event.
## Internal Events
`GET /v1/events` lists the events you can subscribe a Task to, each with a description, plus an `external` array describing third-party triggers available through Event Sources.
```bash theme={null}
curl https://api.crevio.co/v1/events \
-H "Authorization: Bearer YOUR_API_TOKEN"
```
The subscribable internal events:
| Domain | Events |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Leads & forms** | `lead.created`, `form_submission.created`, `form_submission.confirmed` |
| **Customers** | `customer.confirmed` |
| **Checkout & orders** | `checkout.created`, `order.created`, `order.paid` |
| **Refunds** | `refund.created`, `refund.updated` |
| **Invoices** | `invoice.created`, `invoice.paid`, `invoice.past_due`, `invoice.voided` |
| **Products** | `product.created`, `product.updated` |
| **AI tasks** | `task.created`, `task_run.completed`, `task_run.failed`, `task_run.needs_input` |
| **Jobs** | `job.completed`, `job.failed` |
| **Email** | `email_message.received`, `email_message.sent`, `email_message.delivered`, `email_message.bounced`, `email_message.complained`, `email_message.failed` |
## Triggering a Task from an event
Create a Task with `trigger_type: event` and use `event_conditions.event_type` to say which event fires it.
```bash theme={null}
curl -X POST https://api.crevio.co/v1/tasks \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Onboard paid buyers",
"prompt": "When an order is paid, send the buyer a personalized thank-you email referencing what they bought, then add them to the onboarding email sequence.",
"trigger_type": "event",
"event_conditions": { "event_type": "order.paid" },
"agent": "business",
"approval_mode": "autonomous",
"delivery_methods": ["notification"]
}'
```
Every time an order is paid in your account, a new [Task Run](/docs/developer/guides/tasks#task-runs) starts, the agent receives **that order's payload** as the triggering event (so it never has to guess which record it was), and it carries out the prompt. Use `approval_mode: supervised` if you want to approve the agent's actions before they take effect.
Combine event triggers with autonomy: an `autonomous` event-task is a hands-off automation, while a `supervised` one is an assistant that drafts the response and waits for your go-ahead.
### Narrowing which events actually run the agent
`event_type` takes exactly one event, and every occurrence of it starts a run. To react to a *subset* — orders over \$100, email from one sender — add a **`condition_script`**: JavaScript evaluated before the run, with no LLM involved and no credits spent. The triggering payload is available as `event` (`{ type, data }`), and the run happens only when the script's last expression is truthy.
```json theme={null}
{
"trigger_type": "event",
"event_conditions": { "event_type": "order.paid" },
"condition_script": "(event?.data?.amount_total ?? 0) >= 10000;"
}
```
Filtering here rather than in the prompt is what keeps a chatty event cheap: a run that the agent would only have dismissed never starts.
## Event Sources (third-party triggers)
The `external` array in `GET /v1/events` is currently driven by **Event Sources** — connectors that let events from third-party apps trigger your Tasks. This is how activity *outside* Crevio (a new row in a sheet, a message in a channel, a payment in another tool) can put your AI workforce to work.
### 1. Connect the app
Event Sources sit on top of a connected app. Connect Gmail, Google Calendar, Sheets, or whatever else you're triggering on at **/integrations** first — the trigger is deployed as that connected account. A team connection (available to everyone in the account) is the best fit for automations; a personal connection works too, and Crevio deploys the trigger under that member's credential.
### 2. Discover what you can connect
```bash theme={null}
curl "https://api.crevio.co/v1/event_sources/available?app=gmail" \
-H "Authorization: Bearer YOUR_API_TOKEN"
```
`app` is required — it's the app slug (`gmail`, `google_sheets`, `notion`). Add `&q=` to search within it. Each result describes an `id` (the value you pass back as `vendor_component_id`) and the `configurable_props` that trigger accepts — labels, sheets, channels, filters.
### 3. Create the Event Source
```bash theme={null}
curl -X POST https://api.crevio.co/v1/event_sources \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"vendor_component_id": "gmail-new-email-received",
"event_name": "gmail.new_email",
"configured_props": { "labelIds": ["INBOX"] }
}'
```
`event_name` is yours to choose (lowercase, dot-separated). Only the trigger's own settings go in `configured_props` — the connected account is filled in for you from the app you linked in step 1, so there's no account id to look up. If the app isn't connected, the call fails and tells you which one to connect.
### 4. Point a Task at it
External events are namespaced with an `external.` prefix — an `event_name` of `gmail.new_email` is subscribed to as `external.gmail.new_email`:
```bash theme={null}
curl -X POST https://api.crevio.co/v1/tasks \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Triage inbound email",
"prompt": "Summarize the email, and if it is a customer asking about an order, look up their order and draft a reply.",
"trigger_type": "event",
"event_conditions": { "event_type": "external.gmail.new_email" },
"condition_script": "(event?.data?.from || \"\").includes(\"@importantclient.com\");"
}'
```
External activity now drives your agent the same way internal events do — the third-party payload arrives as `event.data`, both in the condition script and in the agent's context.
### Manage event sources
```bash theme={null}
# List your connected sources
curl https://api.crevio.co/v1/event_sources \
-H "Authorization: Bearer YOUR_API_TOKEN"
# Remove one
curl -X DELETE https://api.crevio.co/v1/event_sources/SOURCE_ID \
-H "Authorization: Bearer YOUR_API_TOKEN"
```
## Worked example: the same event, three ways
Say you want everything to happen when **`order.paid`** fires:
1. **Trigger the agent** — an event-Task (`trigger_type: event`, `event_conditions: { "event": "order.paid" }`) sends a personalized welcome and starts onboarding.
2. **React in your own code** — a [webhook endpoint](/docs/developer/guides/webhooks) subscribed to `order.paid` provisions the buyer in your external system.
3. **React to external activity** — an Event Source lets a payment in a *connected app* trigger a Crevio task too.
Events and webhooks are independent and complementary: use Events to put Crevio's AI to work, and webhooks to keep your own systems in sync.
## Next steps
Triggers, agents, autonomy modes, and responding to supervised runs.
Notify your own server when events happen — and verify signatures.
How Events fit into Crevio's broader agentic model.
Let an agent discover and create event sources in code.