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:

Node.js (SDK)
HTTP (cURL)

await flowripple.trigger('order.created', {
  orderId: 'ord_789',
  customer: {
    id: 'cust_123',
    email: '[email protected]',
    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'
});

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": "[email protected]",
        "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	`[email protected]`
`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

{ "name": "John Doe" }

Detected as string.

Numbers

{ "amount": 99.99, "quantity": 5 }

Both detected as number.

Booleans

{ "isActive": true, "hasDiscount": false }

Detected as boolean.

Dates (ISO 8601)

{
  "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

{
  "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

{
  "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

{
  "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:

Navigate to the event in your dashboard
Click on a variable to edit
Update the label to something more descriptive
Save changes

Regenerating Variables

If your payload structure changes, regenerate variables from a new expected payload:

Edit the event’s expected payload
Click “Regenerate Variables”
Review the new variable list
Save changes

Regenerating variables may affect workflows using the old variable paths. Review all workflows using the event after regenerating.

Payload Best Practices

Keep payloads consistent

Always send the same structure for a given event type. Inconsistent payloads lead to missing variables and workflow failures.

// Always include the same fields
await flowripple.trigger('user.signup', {
  userId: user.id,
  email: user.email,
  name: user.name || 'Unknown' // Provide defaults
});

Use meaningful field names

Choose clear, descriptive names that explain the data:

// Good
{ "purchaseAmount": 99.99, "customerEmail": "[email protected]" }

// Avoid
{ "amt": 99.99, "e": "[email protected]" }

Avoid deeply nested structures

Keep nesting to 2-3 levels. Deep nesting creates long variable paths:

// Good
{ "user": { "email": "[email protected]" } }

// Avoid
{ "data": { "user": { "contact": { "email": { "primary": "[email protected]" } } } } }

Include timestamps

Add creation timestamps for audit trails and time-based workflow logic:

{
  "orderId": "ord_123",
  "createdAt": "2024-01-15T10:30:00Z"
}

Getting Started

Events

HTTP Actions

Workflows

Event Payloads & Variables

Event Payloads & Variables

What is an Event Payload?

Automatic Variable Extraction

Variable Properties

Type Detection

Strings

Numbers

Booleans

Dates (ISO 8601)

Objects

Arrays

Using Variables in Workflows

Email Step Example

HTTP Request Example

Managing Variables

Viewing Variables

Editing Variable Labels

Regenerating Variables

Payload Best Practices

What’s Next?

Triggering Events

Event Trigger

Getting Started

Events

HTTP Actions

Workflows

​Event Payloads & Variables

​What is an Event Payload?

​Automatic Variable Extraction

​Variable Properties

​Type Detection

​Strings

​Numbers

​Booleans

​Dates (ISO 8601)

​Objects

​Arrays

​Using Variables in Workflows

​Email Step Example

​HTTP Request Example

​Managing Variables

​Viewing Variables

​Editing Variable Labels

​Regenerating Variables

​Payload Best Practices

​What’s Next?

Triggering Events

Event Trigger

Event Payloads & Variables

What is an Event Payload?

Automatic Variable Extraction

Variable Properties

Type Detection

Strings

Numbers

Booleans

Dates (ISO 8601)

Objects

Arrays

Using Variables in Workflows

Email Step Example

HTTP Request Example

Managing Variables

Viewing Variables

Editing Variable Labels

Regenerating Variables

Payload Best Practices

What’s Next?