Triggering Events

Trigger events from your application to start workflows. You can use the official Node.js SDK or make HTTP requests from any programming language.

Using the SDK

The Flowripple SDK provides a simple, type-safe way to trigger events from Node.js applications.

Installation

npm install @flowripple/sdk

Initialization

import { FlowrippleClient } from '@flowripple/sdk';

const flowripple = new FlowrippleClient({
  apiKey: process.env.FLOWRIPPLE_API_KEY
});

Configuration Options

Option	Type	Required	Description
`apiKey`	string	Yes	Your API key (starts with `frp_`)
`baseUrl`	string	No	Custom API URL. Defaults to `https://api.flowripple.com`
`silent`	boolean	No	If `true`, errors return `false` instead of throwing
`version`	string	No	API version. Defaults to `v1`

const flowripple = new FlowrippleClient({
  apiKey: 'frp_your-api-key',
  baseUrl: 'https://api.flowripple.com',
  silent: false,
  version: 'v1'
});

Basic Trigger

await flowripple.trigger('user.signup', {
  userId: 'usr_123',
  email: '[email protected]',
  name: 'John Doe'
});

The trigger method accepts:

identifier (string): The event identifier (e.g., user.signup)
data (object, optional): JSON payload with event data
options (object, optional): Trigger options including idempotency key

Idempotent Requests

Use idempotency keys to safely retry requests without creating duplicate events. This is useful when network issues occur or you need to ensure exactly-once processing.

await flowripple.trigger('order.created', {
  orderId: 'ord_456',
  amount: 99.99
}, {
  idempotencyKey: 'order-ord_456-creation'
});

Key scoping: Idempotency keys are scoped per event identifier. This means:

user.signup with key abc123 and order.created with key abc123 are independent
The same key can be reused across different event types

Key requirements:

Maximum 256 characters
Alphanumeric characters, hyphens (-), underscores (_), colons (:), and periods (.) allowed

Use a unique value tied to your business logic, such as combining the entity type and ID (e.g., order-ord_456-creation). This ensures retries are safe while allowing different operations to proceed independently.

When a request with an idempotency key matches a previous request:

The cached response is returned immediately
No duplicate event is created
The response includes cached: true to indicate it was served from cache

Cached responses are stored for 24 hours.

Error Handling

By default, failed triggers throw an error:

try {
  await flowripple.trigger('user.signup', { userId: 'usr_123' });
} catch (error) {
  console.error('Failed to trigger event:', error.message);
}

Silent Mode

Enable silent mode to return false on failure instead of throwing:

const flowripple = new FlowrippleClient({
  apiKey: process.env.FLOWRIPPLE_API_KEY,
  silent: true
});

const result = await flowripple.trigger('user.signup', { userId: 'usr_123' });

if (result === false) {
  console.log('Event trigger failed silently');
}

Use silent mode in non-critical paths where you don’t want event failures to interrupt your application flow.

Using the HTTP API

Trigger events from any programming language using HTTP requests.

Endpoint

POST https://api.flowripple.com/api/v1/trigger

Headers

Header	Value
`Content-Type`	`application/json`
`x-api-key`	Your API key

Request Body

{
  "identifier": "user.signup",
  "data": {
    "userId": "usr_123",
    "email": "[email protected]",
    "name": "John Doe"
  },
  "idempotencyKey": "signup-usr_123"
}

Field	Type	Required	Description
`identifier`	string	Yes	Event identifier
`data`	object	No	Event payload
`idempotencyKey`	string	No	Unique key for idempotent requests (max 256 chars, alphanumeric + `-_:.`)

Response

Success (200)

{
  "success": true,
  "jobId": "job_abc123",
  "message": "Event queued for processing"
}

Success - Cached (200) When using an idempotency key that matches a previous request:

{
  "success": true,
  "jobId": "job_abc123",
  "message": "Event queued for processing",
  "cached": true
}

Error (4xx/5xx)

{
  "error": "Event trigger failed",
  "message": "Invalid API key"
}

Code Examples

curl -X POST https://api.flowripple.com/api/v1/trigger \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "identifier": "user.signup",
    "data": {
      "userId": "usr_123",
      "email": "[email protected]",
      "name": "John Doe"
    },
    "idempotencyKey": "signup-usr_123"
  }'

Auto-Creation on First Trigger

When you trigger an event identifier that doesn’t exist, Flowripple automatically creates the event:

// This creates "order.refunded" if it doesn't exist
await flowripple.trigger('order.refunded', {
  orderId: 'ord_456',
  amount: 99.99,
  reason: 'customer_request'
});

The auto-created event:

Uses the identifier as the event name
Extracts variables from the payload
Appears in your dashboard immediately

Auto-creation is convenient for development. For production, consider pre-creating events in the dashboard to define expected payload structures.

Best Practices

Store API keys securely

Never hardcode API keys in your source code. Use environment variables or a secrets manager:

// Good
const flowripple = new FlowrippleClient({
  apiKey: process.env.FLOWRIPPLE_API_KEY
});

// Bad - never do this
const flowripple = new FlowrippleClient({
  apiKey: 'frp_abc123...'
});

Handle trigger failures gracefully

Decide how your application should behave if an event trigger fails:

// Option 1: Log and continue (non-critical events)
const flowripple = new FlowrippleClient({
  apiKey: process.env.FLOWRIPPLE_API_KEY,
  silent: true
});

// Option 2: Throw and handle (critical events)
try {
  await flowripple.trigger('payment.completed', data);
} catch (error) {
  // Log to monitoring service
  // Maybe retry or queue for later
}

Send consistent payloads

Always send the same fields for a given event type:

// Create a helper to ensure consistency
function triggerUserSignup(user: User) {
  return flowripple.trigger('user.signup', {
    userId: user.id,
    email: user.email,
    name: user.name || 'Unknown',
    createdAt: new Date().toISOString()
  });
}

Use separate keys per environment

Create different API keys for development, staging, and production to isolate environments and manage access.

Use idempotency keys for critical events

For important events like payments or order creation, always use idempotency keys to prevent duplicates:

// Generate a unique key based on business logic
const idempotencyKey = `payment-${paymentId}-${Date.now()}`;

await flowripple.trigger('payment.completed', {
  paymentId,
  amount,
  customerId
}, {
  idempotencyKey
});

Good idempotency key patterns:

order-{orderId}-creation - for order events
payment-{paymentId}-{timestamp} - for payment events
user-{userId}-signup - for one-time user events

What’s Next?

Monitoring Captures

Track triggered events and analyze capture data.

Quickstart Guide

Complete end-to-end guide for your first workflow.

Getting Started

Events

HTTP Actions

Workflows

Triggering Events

Triggering Events

Using the SDK

Installation

Initialization

Configuration Options

Basic Trigger

Idempotent Requests

Error Handling

Silent Mode

Using the HTTP API

Endpoint

Headers

Request Body

Response

Code Examples

Auto-Creation on First Trigger

Best Practices

What’s Next?

Monitoring Captures

Quickstart Guide

Getting Started

Events

HTTP Actions

Workflows

​Triggering Events

​Using the SDK

​Installation

​Initialization

​Configuration Options

​Basic Trigger

​Idempotent Requests

​Error Handling

​Silent Mode

​Using the HTTP API

​Endpoint

​Headers

​Request Body

​Response

​Code Examples

​Auto-Creation on First Trigger

​Best Practices

​What’s Next?

Monitoring Captures

Quickstart Guide

Triggering Events

Using the SDK

Installation

Initialization

Configuration Options

Basic Trigger

Idempotent Requests

Error Handling

Silent Mode

Using the HTTP API

Endpoint

Headers

Request Body

Response

Code Examples

Auto-Creation on First Trigger

Best Practices

What’s Next?