> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowripple.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Event Payloads & Variables
> Understand how event payloads work and how variables are automatically extracted for use in workflows.
# Event Payloads & Variables
Event payloads are JSON objects containing data about an occurrence in your system. Flowripple automatically extracts variables from payloads, making the data available throughout your workflows.
## What is an Event Payload?
A payload is the JSON data you send when triggering an event. It contains context about what happened:
```typescript theme={null}
await flowripple.trigger('order.created', {
orderId: 'ord_789',
customer: {
id: 'cust_123',
email: 'customer@example.com',
name: 'Jane Smith'
},
items: [
{ sku: 'PROD-001', quantity: 2, price: 29.99 },
{ sku: 'PROD-002', quantity: 1, price: 49.99 }
],
total: 109.97,
createdAt: '2024-01-15T14:30:00Z'
});
```
```bash theme={null}
curl -X POST https://api.flowripple.com/api/v1/trigger \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"identifier": "order.created",
"data": {
"orderId": "ord_789",
"customer": {
"id": "cust_123",
"email": "customer@example.com",
"name": "Jane Smith"
},
"items": [
{ "sku": "PROD-001", "quantity": 2, "price": 29.99 },
{ "sku": "PROD-002", "quantity": 1, "price": 49.99 }
],
"total": 109.97,
"createdAt": "2024-01-15T14:30:00Z"
}
}'
```
This payload contains:
* Order identification (`orderId`)
* Customer information (nested `customer` object)
* Order items (array of products)
* Order total and timestamp
## Automatic Variable Extraction
When Flowripple receives a payload, it automatically extracts variables using dot notation paths:
| Payload Path | Variable | Type | Sample Value |
| ---------------- | ------------------------ | ------ | ---------------------- |
| `orderId` | `trigger.orderId` | string | `ord_789` |
| `customer.id` | `trigger.customer.id` | string | `cust_123` |
| `customer.email` | `trigger.customer.email` | string | `customer@example.com` |
| `customer.name` | `trigger.customer.name` | string | `Jane Smith` |
| `total` | `trigger.total` | number | `109.97` |
| `createdAt` | `trigger.createdAt` | date | `2024-01-15T14:30:00Z` |
All event variables are prefixed with `trigger.` to distinguish them from variables created by workflow steps.
## Variable Properties
Each extracted variable has these properties:
| Property | Description |
| ---------- | ------------------------------------------------------------------- |
| **Path** | Dot notation path to the value (e.g., `customer.email`) |
| **Label** | Human-readable name shown in the variable picker |
| **Type** | Data type: `string`, `number`, `boolean`, `date`, `object`, `array` |
| **Sample** | Example value from the expected payload |
## Type Detection
Flowripple automatically detects variable types based on values:
### Strings
```json theme={null}
{ "name": "John Doe" }
```
Detected as `string`.
### Numbers
```json theme={null}
{ "amount": 99.99, "quantity": 5 }
```
Both detected as `number`.
### Booleans
```json theme={null}
{ "isActive": true, "hasDiscount": false }
```
Detected as `boolean`.
### Dates (ISO 8601)
```json theme={null}
{
"createdAt": "2024-01-15T10:30:00Z",
"expiresAt": "2024-02-15T10:30:00.000Z"
}
```
Use ISO 8601 format for dates (`YYYY-MM-DDTHH:mm:ssZ`). Flowripple recognizes this format and provides date-specific functionality in workflow steps.
### Objects
```json theme={null}
{
"user": {
"id": "usr_123",
"profile": {
"firstName": "John"
}
}
}
```
Nested objects are flattened into dot notation paths:
* `trigger.user.id` → `usr_123`
* `trigger.user.profile.firstName` → `John`
### Arrays
```json theme={null}
{
"tags": ["premium", "verified"],
"items": [{ "id": 1 }, { "id": 2 }]
}
```
Arrays are accessible as variables but individual elements require specific workflow logic to iterate.
## Using Variables in Workflows
Reference variables in workflow step configurations using the `{{variable.path}}` syntax:
### Email Step Example
```
To: {{trigger.customer.email}}
Subject: Order #{{trigger.orderId}} Confirmed
Body: Hi {{trigger.customer.name}}, your order total is ${{trigger.total}}.
```
### HTTP Request Example
```json theme={null}
{
"url": "https://api.example.com/orders",
"body": {
"externalOrderId": "{{trigger.orderId}}",
"customerEmail": "{{trigger.customer.email}}",
"amount": {{trigger.total}}
}
}
```
Use the variable picker in any workflow step to browse available variables. Click on a variable to insert it at the cursor position.
## Managing Variables
### Viewing Variables
In the Events section of your dashboard, click on an event to view its extracted variables. Each variable shows:
* Variable path
* Detected type
* Sample value from the expected payload
### Editing Variable Labels
Variable paths are auto-generated, but you can customize the display labels:
1. Navigate to the event in your dashboard
2. Click on a variable to edit
3. Update the label to something more descriptive
4. Save changes
### Regenerating Variables
If your payload structure changes, regenerate variables from a new expected payload:
1. Edit the event's expected payload
2. Click **"Regenerate Variables"**
3. Review the new variable list
4. Save changes
Regenerating variables may affect workflows using the old variable paths. Review all workflows using the event after regenerating.
## Payload Best Practices
Always send the same structure for a given event type. Inconsistent payloads lead to missing variables and workflow failures.
```typescript theme={null}
// Always include the same fields
await flowripple.trigger('user.signup', {
userId: user.id,
email: user.email,
name: user.name || 'Unknown' // Provide defaults
});
```
Choose clear, descriptive names that explain the data:
```json theme={null}
// Good
{ "purchaseAmount": 99.99, "customerEmail": "a@b.com" }
// Avoid
{ "amt": 99.99, "e": "a@b.com" }
```
Keep nesting to 2-3 levels. Deep nesting creates long variable paths:
```json theme={null}
// Good
{ "user": { "email": "a@b.com" } }
// Avoid
{ "data": { "user": { "contact": { "email": { "primary": "a@b.com" } } } } }
```
Add creation timestamps for audit trails and time-based workflow logic:
```json theme={null}
{
"orderId": "ord_123",
"createdAt": "2024-01-15T10:30:00Z"
}
```
## What's Next?
Learn how to trigger events from your application.
Configure workflows to start when events occur.