" }`.
## Matching Rules
A workflow with a `webhook` trigger is selected when:
1. The event arrived as `custom` (through `/webhooks/custom/:companyId/:path`) and the trigger's `path` equals the `:path` segment. The comparison is case-insensitive and treats `.`, `-`, and `_` as equivalent, so `order.received` and `order-received` both match. A leading slash on `path` never matches.
2. Otherwise, the trigger's `provider` equals the event's provider.
Only active workflows in the receiving company are considered.
## Provider Examples
### Stripe
Stripe events arrive either through the Nango forwarder (after you authorize Stripe via Nango Connect) or through the dedicated Connect endpoint.
```json
{
"name": "Payment Received Notification",
"trigger": {
"type": "webhook",
"provider": "stripe",
"path": "stripe"
},
"steps": [...]
}
```
**Common Stripe Events:**
- `invoice.paid` - Invoice was paid
- `invoice.payment_failed` - Payment attempt failed
- `payment_intent.succeeded` - Payment completed
- `customer.created` - New customer created
- `subscription.created` - New subscription started
- `subscription.canceled` - Subscription was canceled
### Salesforce
Salesforce supports three webhook types:
```json
{
"trigger": {
"type": "salesforce_event",
"eventKind": "platform_event",
"platformEventName": "Invoice_Created__e"
}
}
```
```json
{
"trigger": {
"type": "salesforce_event",
"eventKind": "cdc",
"cdcEntity": "Opportunity",
"cdcChangeTypes": ["create", "update"]
}
}
```
```json
{
"trigger": {
"type": "webhook",
"provider": "salesforce",
"path": "salesforce"
}
}
```
**Salesforce CDC Change Types:**
- `create` - Record created
- `update` - Record updated
- `delete` - Record deleted
- `undelete` - Record restored
### HubSpot
HubSpot events arrive through `POST /webhooks/hubspot` and are matched by the dedicated `hubspot_event` trigger type, which supports per-event selection:
```json
{
"trigger": {
"type": "hubspot_event",
"eventKind": "deal.propertyChange",
"propertyName": "dealstage"
}
}
```
**HubSpot Event Kinds:**
- `contact.propertyChange` - Contact property changed
- `company.propertyChange` - Company property changed
- `deal.propertyChange` - Deal property changed
- `deal.creation` - Deal created
- `deal.deletion` - Deal deleted
- `*` - Match all events
### QuickBooks
```json
{
"trigger": {
"type": "webhook",
"provider": "quickbooks",
"path": "quickbooks"
}
}
```
QuickBooks event types are derived from the notification entity and operation, lowercased — for example `invoice.create`, `payment.update`, `customer.delete`.
### PandaDoc
```json
{
"trigger": {
"type": "webhook",
"provider": "pandadoc",
"path": "pandadoc"
}
}
```
**PandaDoc Events:**
- `document_state_changed` - Document status changed
- `recipient_completed` - Recipient signed
- `document_completed` - All signatures collected
- `document_paid` - Payment received
### NetSuite
```json
{
"trigger": {
"type": "webhook",
"provider": "netsuite",
"path": "netsuite"
}
}
```
### Custom Webhooks
For providers not listed above, use custom webhooks. `path` is the match key — no `provider` field:
```json
{
"trigger": {
"type": "webhook",
"path": "my-integration"
}
}
```
**Custom Webhook URL:**
```
https://your-domain.com/webhooks/custom/{COMPANY_ID}/my-integration
```
The body is parsed as JSON when possible; a non-JSON payload is wrapped as `{ "rawBody": "..." }`. There is no signature check on this route — treat the URL as a shared secret and serve it over HTTPS only.
## Event Filtering
The `events` array is accepted by the trigger schema but is **not** applied when matching. Every event that reaches the matched route starts the workflow.
To narrow what runs:
- Subscribe to only the events you want in the provider's own webhook settings.
- Put a Condition block at the top of the workflow and branch on `{{input}}`.
## Signature Verification
Verification happens at the route, before workflow matching.
| Route | What is checked |
|-------|-----------------|
| `POST /webhooks/:provider` | The provider handler's Svix signature check. A failure returns `401 Invalid signature`; a handler that throws returns `500 Verification error` |
| `POST /webhooks/nango` | Nango HMAC over the raw body. Fail-closed: a missing secret returns `500`, a missing or bad signature returns `401` |
| `POST /webhooks/stripe` | `stripe-signature` (HMAC-SHA256 over `${timestamp}.${rawBody}`, 5-minute window) when `STRIPE_WEBHOOK_SECRET` is set |
| `POST /webhooks/custom/:companyId/:path` | Nothing |
Store webhook signing secrets securely in environment variables. Never commit them to version control.
### Handling Verification Failures
When signature verification fails, the webhook returns `401 Unauthorized`:
```json
{
"error": "Invalid signature"
}
```
Check that:
1. Your signing secret matches the provider's configuration
2. The request hasn't been tampered with
3. The timestamp is within acceptable bounds (for Stripe)
## Webhook Response
The Stripe and custom routes return:
```json
{
"received": true,
"eventId": "evt_xxx",
"workflowsTriggered": 2
}
```
| Field | Description |
|-------|-------------|
| `received` | Always `true` for successful receipt |
| `eventId` | Unique identifier for this webhook event |
| `workflowsTriggered` | Number of workflows triggered by this event |
The `POST /webhooks/:provider` dispatcher returns `{ "received": true, "count": N }`, where `count` is the number of events in the batch that resolved to a connection and were routed.
## Input Data
The full webhook payload is available in your workflow as `{{input}}`:
### Stripe Example
```json
{
"input": {
"id": "evt_1234",
"type": "invoice.paid",
"data": {
"object": {
"id": "in_xxx",
"amount_paid": 9900,
"customer": "cus_xxx",
"customer_email": "customer@example.com"
}
}
}
}
```
Access nested data in your steps:
```json
{
"config": {
"to": "{{input.data.object.customer_email}}",
"amount": "{{input.data.object.amount_paid / 100}}"
}
}
```
### Salesforce CDC Example
```json
{
"input": {
"ChangeEventHeader": {
"entityName": "Opportunity",
"changeType": "UPDATE",
"changedFields": ["Amount", "StageName"]
},
"Id": "006xxx",
"Name": "Big Deal",
"Amount": 50000,
"StageName": "Closed Won"
}
}
```
## Webhook Events Table
All incoming webhooks are stored in the `webhook_events` table for audit and replay:
| Field | Description |
|-------|-------------|
| `id` | Unique event ID |
| `company_id` | Company that received this event |
| `provider` | Provider name (stripe, salesforce, etc.) |
| `event_type` | Event type (invoice.paid, etc.) |
| `event_id` | Provider's event ID |
| `payload` | Full event payload (JSON) |
| `signature_verified` | Verification status |
| `status` | Processing status |
| `workflows_triggered` | Array of triggered workflow runs |
## Testing Webhooks
### Using cURL
The custom route needs no signature, which makes it the simplest one to exercise end to end:
```bash
curl -X POST https://workflow.loopfour.ai/webhooks/custom/{COMPANY_ID}/my-integration \
-H "Content-Type: application/json" \
-d '{
"orderId": "12345",
"total": 99.99
}'
```
### Using Stripe CLI
```bash
# Forward Stripe webhooks to the Connect endpoint on localhost
stripe listen --forward-to localhost:3000/webhooks/stripe
```
A Stripe event with no `account` field cannot be attributed to a company. It is acknowledged with `{ "received": true, "ignored": true }` and no workflow runs.
### Using ngrok
```bash
# Expose local server
ngrok http 3000
# Use the ngrok URL in provider webhook settings
# https://abc123.ngrok.io/webhooks/stripe
```
## Troubleshooting
### Webhook Not Triggering Workflow
1. **Check workflow status** - Must be `active`
2. **Check the provider match** - the trigger's `provider` must equal the provider the event arrived as. Events forwarded by Nango for an unmapped provider key arrive as `custom`, not under the provider's own name
3. **Check the path** - for custom webhooks, the trigger's `path` must equal the URL's `:path` segment, with no leading slash
4. **Check signature** - ensure signing secrets are configured
5. **Review webhook events** - check the `webhook_events` table
### Duplicate Events
Loopfour does not drop repeated events — the provider's event id is stored and
indexed on `webhook_events` so you can spot duplicates, but a redelivered event
starts the workflow again. If you receive duplicates:
1. Ensure idempotent workflow design
2. Check provider retry settings
3. Verify webhook acknowledgement is reaching provider
### Timeout Issues
Webhooks must respond within provider timeouts:
- Stripe: 30 seconds
- HubSpot: 5 seconds
- QuickBooks: 30 seconds
The API acknowledges webhooks immediately and processes asynchronously.
## Next Steps
Run workflows on a time-based schedule
Trigger workflows programmatically
Trigger from Slack events and commands
# Troubleshooting (/docs/troubleshooting)
Common issues and solutions
## Troubleshooting
Find solutions to common issues.
Troubleshooting Loopfour usually starts by separating setup problems from execution problems. Setup issues involve authentication, missing connections, expired tokens, provider permissions, or invalid workflow configuration. Execution issues happen after a workflow starts: a step may receive unexpected input, a provider may reject a request, a condition may route down the wrong branch, or an approval may remain pending longer than expected. The guides in this section help you narrow the failure before changing workflow logic.
When a run fails, collect the run ID, workflow ID, trigger payload, failed step name, provider response, and any recent connection changes. That information is usually enough to decide whether the problem belongs in the workflow definition, the integration credential, the external system, or the input data. Avoid retrying blindly in finance workflows. A retry can create duplicate invoices, messages, or records if the failed step was not idempotent. Inspect the run history first, then retry only after you understand where the previous attempt stopped.
For recurring issues, compare several failed runs instead of treating each failure as isolated. If the same provider response appears every time, start with connection permissions or request shape. If failures occur only for certain customers, invoices, or contracts, inspect the input data and mapping rules. If the workflow succeeds after manual replay, look for timing assumptions in the trigger or upstream system. This pattern keeps debugging grounded in evidence rather than guesses.
API errors and how to fix them
OAuth and integration problems
Debug workflow execution issues
# Common Errors (/docs/troubleshooting/common-errors)
API errors and how to fix them
## Common Errors
## Authentication Errors
### 401 Unauthorized
```json
{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
}
```
**Solution:** Check that your API key is correct and included in the `x-api-key` header.
### 403 Forbidden
```json
{
"error": {
"code": "FORBIDDEN",
"message": "Access denied to this resource"
}
}
```
**Solution:** Verify your API key has access to the requested company/resource.
## Rate Limiting
### 429 Too Many Requests
```json
{
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded. Limit: 100 requests per minute."
}
}
```
**Solution:**
- Wait for the rate limit window to reset (check `X-RateLimit-Reset` header)
- Reduce request frequency
- Implement exponential backoff
## Validation Errors
### 400 Bad Request
```json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid workflow configuration",
"details": [
{ "field": "steps[0].id", "message": "Step ID is required" }
]
}
}
```
**Solution:** Check the `details` array for specific field errors.
## Not Found
### 404 Not Found
```json
{
"error": {
"code": "NOT_FOUND",
"message": "Workflow not found"
}
}
```
**Solution:** Verify the resource ID exists and belongs to your company.
# Connection Issues (/docs/troubleshooting/connection-issues)
OAuth and integration problems
## Connection Issues
## OAuth Flow Failures
### "Access Denied" During OAuth
**Possible Causes:**
- User cancelled the OAuth flow
- Missing required scopes
- Account doesn't have required permissions
**Solutions:**
1. Retry the OAuth flow
2. Check that your OAuth app has the required scopes
3. Verify the user has admin permissions in the target system
### "Token Expired" Error
**Cause:** The OAuth refresh token has expired or been revoked.
**Solution:** Re-authenticate by going through the OAuth flow again.
## Connection Status: Error
### Salesforce
- Check that the Connected App is still active
- Verify API access is enabled for the user
- Confirm the user's Salesforce license includes API access
### HubSpot
- Verify the HubSpot account is not deactivated
- Check that required scopes are still granted
- Ensure the app isn't uninstalled from HubSpot
### Stripe
- Confirm the Stripe account is in good standing
- Check API key permissions
- Verify the account isn't in test mode (if using live mode)
## Webhook Issues
### Webhooks Not Received
1. Check the webhook URL is correctly configured in the provider
2. Verify your firewall allows incoming requests
3. Check the provider's webhook logs for delivery errors
### Signature Verification Failed
1. Verify the webhook secret is correctly configured
2. Check the request body isn't being modified by middleware
3. Ensure you're using the raw request body for verification
# Workflow Debugging (/docs/troubleshooting/workflow-debugging)
Debug workflow execution issues
## Workflow Debugging
## Viewing Run Details
Get detailed information about a workflow run:
```bash
curl https://workflow.loopfour.ai/api/v1/runs/{runId} \
-H "x-api-key: YOUR_API_KEY"
```
The response includes:
- Overall run status
- Each step's status, input, and output
- Error messages for failed steps
- Timing information
## Common Step Failures
### Template Variable Errors
**Error:** `Cannot read property 'x' of undefined`
**Cause:** Referencing a field that doesn't exist.
**Solution:** Check the input data structure and use optional chaining:
```
{{input.data?.object?.id}}
```
### Action Errors
**Error:** `Integration error: Rate limited`
**Cause:** The external API rate limited the request.
**Solution:** Add retry configuration to the step:
```json
{
"retries": 3,
"retryDelay": 5000,
"retryBackoff": "exponential"
}
```
### Condition Errors
**Error:** `Invalid condition expression`
**Cause:** Malformed condition syntax.
**Solution:** Verify operator and value types match.
## Testing Workflows
### Test with Mock Input
```bash
curl -X POST https://workflow.loopfour.ai/api/v1/workflows/{id}/run \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"input": {
"test": true,
"data": { "example": "value" }
}
}'
```
### Dry Run Mode
Execute without side effects:
```bash
curl -X POST https://workflow.loopfour.ai/api/v1/workflows/{id}/run?dryRun=true \
-H "x-api-key: YOUR_API_KEY"
```
## Logging
Enable verbose logging for debugging:
```json
{
"settings": {
"logging": "verbose"
}
}
```
# Tutorials (/docs/tutorials)
Step-by-step workflow guides
## Tutorials
Learn to build real-world workflows with these step-by-step tutorials.
Tutorials show how the primitives in the rest of the docs fit together into complete finance operations. Each guide starts with a business event, identifies the systems involved, then builds the trigger, steps, mappings, and exception paths needed to run the workflow safely. Use them as working patterns rather than copy-only recipes: the exact provider, field names, and approval thresholds should match your team's process.
The most useful way to follow a tutorial is to run it first with test data, inspect the run output, and then replace the sample fields with your own operational records. Pay special attention to where the workflow reads source data, where it writes final state, and where humans review ambiguous or high-risk cases. Those boundaries are what make a workflow reliable enough for billing, revenue operations, customer onboarding, or accounting handoffs.
After you complete a tutorial, review the workflow as if it were headed to production. Confirm the trigger cannot fire on the wrong event, the connected accounts point to the intended workspace or sandbox, and every external write has enough context for reconciliation. Then add the monitoring, retry, and exception rules your team expects. A tutorial should give you a working foundation, but production workflows still need your team's approval thresholds and ownership model.
Create invoices when CRM deals close
Sync CRM deals to contracts
Automate customer onboarding flow
# Customer Onboarding (/docs/tutorials/customer-onboarding)
Automate new customer setup across multiple systems
## Customer Onboarding Tutorial
Learn how to automate new customer onboarding across multiple systems when a Stripe subscription is created, ensuring consistent setup and immediate engagement.
## The Problem
When a new customer signs up, teams typically:
1. Manually create the customer in the accounting system (QuickBooks/NetSuite)
2. Add the contact to the CRM (HubSpot/Salesforce)
3. Send a welcome email with setup instructions
4. Notify the customer success team in Slack
5. Create onboarding tasks or projects
6. Update spreadsheets or dashboards
This manual process causes:
- **Delayed onboarding** - Hours or days before customer is fully set up
- **Inconsistent data** - Customer info varies across systems
- **Missed steps** - Someone forgets to update a system
- **Poor first impression** - Customer waits for manual actions
- **Team bottlenecks** - One person becomes the onboarding gatekeeper
## The Solution
Build a workflow that automatically:
1. Triggers when a Stripe subscription is created
2. Creates the customer in QuickBooks for invoicing
3. Creates or updates the contact in HubSpot as a customer
4. Sends a personalized welcome email
5. Notifies the customer success team in Slack
6. (Optional) Creates an onboarding project or task
## What You'll Build
```
Stripe Subscription Created
│
▼
┌───────────────────┐
│ Get Stripe │
│ Customer Details │
└─────────┬─────────┘
│
┌─────┴─────┐
▼ ▼
┌───────────┐ ┌───────────┐
│ Create │ │ Create/ │
│ QuickBooks│ │ Update │
│ Customer │ │ HubSpot │
└─────┬─────┘ └─────┬─────┘
└──────┬──────┘
│
▼
┌───────────────────┐
│ Send Welcome │
│ Email │
└─────────┬─────────┘
│
▼
┌───────────────────┐
│ Notify Team │
│ in Slack │
└───────────────────┘
```
## Prerequisites
### Required Connections
| Provider | Connection Type | Purpose |
|----------|----------------|---------|
| Stripe | OAuth via Nango | Receive webhooks, get customer data |
| QuickBooks | OAuth via Nango | Create accounting customers |
| HubSpot | OAuth via Nango | Manage CRM contacts |
| Slack | OAuth via Nango | Team notifications |
| Email Provider | OAuth or API Key | Welcome emails |
### Stripe Setup
1. **Configure Webhook** in Stripe Dashboard:
- Developers → Webhooks → Add endpoint
- URL: `https://your-domain.com/webhooks/stripe/{companyId}`
- Events: `customer.subscription.created`
2. **Note your webhook signing secret** for verification
### QuickBooks Setup
Ensure you have:
- An active QuickBooks Online account
- OAuth connection configured in Nango
### HubSpot Setup
1. **Create Custom Properties** (recommended):
- `stripe_customer_id` (Single-line text)
- `stripe_subscription_id` (Single-line text)
- `subscription_plan` (Dropdown)
- `mrr` (Number - currency)
## Step-by-Step Implementation
### Step 1: Create the Workflow
Start with the Stripe webhook trigger:
```json
{
"name": "Customer Onboarding",
"description": "Automate new customer setup when Stripe subscription is created",
"trigger": {
"type": "webhook",
"provider": "stripe",
"events": ["customer.subscription.created"]
},
"steps": []
}
```
### Step 2: Extract Customer Information
Parse the subscription data:
```json
{
"id": "extract-customer-data",
"type": "transform",
"name": "Extract Customer Data",
"config": {
"operation": "map",
"data": {
"customerId": "{{input.data.object.customer}}",
"subscriptionId": "{{input.data.object.id}}",
"planName": "{{input.data.object.items.data.[0].plan.nickname}}",
"planAmount": "{{input.data.object.items.data.[0].plan.amount}}",
"interval": "{{input.data.object.items.data.[0].plan.interval}}",
"status": "{{input.data.object.status}}"
}
}
}
```
### Step 3: Get Full Customer Details from Stripe
Retrieve the complete customer profile:
```json
{
"id": "get-stripe-customer",
"type": "action",
"name": "Get Stripe Customer Details",
"config": {
"connector": "stripe",
"action": "getCustomer",
"customerId": "{{steps.extract-customer-data.output.customerId}}"
}
}
```
**Output includes:**
- `name` - Customer name
- `email` - Email address
- `phone` - Phone number (if provided)
- `address` - Billing address
- `metadata` - Custom fields
### Step 4: Create QuickBooks Customer
Create the customer in your accounting system:
```json
{
"id": "create-qb-customer",
"type": "action",
"name": "Create QuickBooks Customer",
"config": {
"connector": "quickbooks",
"action": "createCustomer",
"DisplayName": "{{steps.get-stripe-customer.output.name}}",
"CompanyName": "{{steps.get-stripe-customer.output.metadata.company_name}}",
"PrimaryEmailAddr": {
"Address": "{{steps.get-stripe-customer.output.email}}"
},
"PrimaryPhone": {
"FreeFormNumber": "{{steps.get-stripe-customer.output.phone}}"
},
"BillAddr": {
"Line1": "{{steps.get-stripe-customer.output.address.line1}}",
"City": "{{steps.get-stripe-customer.output.address.city}}",
"CountrySubDivisionCode": "{{steps.get-stripe-customer.output.address.state}}",
"PostalCode": "{{steps.get-stripe-customer.output.address.postal_code}}",
"Country": "{{steps.get-stripe-customer.output.address.country}}"
},
"Notes": "Stripe Customer ID: {{steps.get-stripe-customer.output.id}}\nSubscription: {{steps.extract-customer-data.output.planName}}"
},
"onError": {
"action": "continue",
"fallback": { "Id": null }
}
}
```
### Step 5: Create or Update HubSpot Contact
Add the customer to your CRM:
```json
{
"id": "upsert-hubspot-contact",
"type": "action",
"name": "Create/Update HubSpot Contact",
"config": {
"connector": "hubspot",
"action": "createContact",
"email": "{{steps.get-stripe-customer.output.email}}",
"properties": {
"firstname": "{{steps.get-stripe-customer.output.name | split: ' ' | first}}",
"lastname": "{{steps.get-stripe-customer.output.name | split: ' ' | last}}",
"phone": "{{steps.get-stripe-customer.output.phone}}",
"company": "{{steps.get-stripe-customer.output.metadata.company_name}}",
"lifecyclestage": "customer",
"stripe_customer_id": "{{steps.get-stripe-customer.output.id}}",
"stripe_subscription_id": "{{steps.extract-customer-data.output.subscriptionId}}",
"subscription_plan": "{{steps.extract-customer-data.output.planName}}",
"mrr": "{{steps.extract-customer-data.output.planAmount | divided_by: 100}}"
}
},
"onError": {
"action": "continue",
"fallback": { "id": null }
}
}
```
**Key properties:**
- `lifecyclestage: customer` - Marks them as a paying customer
- Custom Stripe fields for tracking
### Step 6: Send Welcome Email
Send a personalized welcome email:
```json
{
"id": "send-welcome-email",
"type": "email",
"name": "Send Welcome Email",
"config": {
"action": "send",
"provider": "resend",
"to": "{{steps.get-stripe-customer.output.email}}",
"from": "onboarding@yourcompany.com",
"subject": "Welcome to {{steps.extract-customer-data.output.planName}}!",
"body": {
"html": "Welcome, {{steps.get-stripe-customer.output.name}}!
Thank you for subscribing to {{steps.extract-customer-data.output.planName}}. We're excited to have you on board!
Getting Started
Here are your next steps:
- Complete your profile setup
- Read our quickstart guide
- Book an onboarding call with our team
If you have any questions, reply to this email or reach out to support@yourcompany.com.
Welcome aboard!
The {{steps.extract-customer-data.output.planName}} Team
"
},
"template_variables": {
"customer_name": "{{steps.get-stripe-customer.output.name}}",
"plan_name": "{{steps.extract-customer-data.output.planName}}",
"app_url": "https://app.yourcompany.com"
}
}
}
```
### Step 7: Notify Customer Success Team
Alert the team about the new customer:
```json
{
"id": "notify-cs-team",
"type": "slack",
"name": "Notify Customer Success",
"config": {
"action": "sendMessage",
"channel": "#new-customers",
"blocks": [
{
"type": "header",
"text": {
"type": "plain_text",
"text": "New Customer Signed Up!"
}
},
{
"type": "section",
"fields": [
{
"type": "mrkdwn",
"text": "*Customer:*\n{{steps.get-stripe-customer.output.name}}"
},
{
"type": "mrkdwn",
"text": "*Plan:*\n{{steps.extract-customer-data.output.planName}}"
},
{
"type": "mrkdwn",
"text": "*Email:*\n{{steps.get-stripe-customer.output.email}}"
},
{
"type": "mrkdwn",
"text": "*MRR:*\n${{steps.extract-customer-data.output.planAmount | divided_by: 100}}/{{steps.extract-customer-data.output.interval}}"
}
]
},
{
"type": "context",
"elements": [
{
"type": "mrkdwn",
"text": "QuickBooks: {{#if steps.create-qb-customer.output.Id}}Created{{else}}Skipped{{/if}} | HubSpot: {{#if steps.upsert-hubspot-contact.output.id}}Created{{else}}Skipped{{/if}}"
}
]
},
{
"type": "actions",
"elements": [
{
"type": "button",
"text": {
"type": "plain_text",
"text": "View in Stripe"
},
"url": "https://dashboard.stripe.com/customers/{{steps.get-stripe-customer.output.id}}"
},
{
"type": "button",
"text": {
"type": "plain_text",
"text": "View in HubSpot"
},
"url": "https://app.hubspot.com/contacts/YOUR_PORTAL_ID/contact/{{steps.upsert-hubspot-contact.output.id}}"
}
]
}
]
}
}
```
## Complete Workflow
Here's the complete workflow JSON:
```json
{
"name": "Customer Onboarding",
"description": "Automate new customer setup when Stripe subscription is created",
"trigger": {
"type": "webhook",
"provider": "stripe",
"events": ["customer.subscription.created"]
},
"steps": [
{
"id": "extract-customer-data",
"type": "transform",
"name": "Extract Customer Data",
"config": {
"operation": "map",
"data": {
"customerId": "{{input.data.object.customer}}",
"subscriptionId": "{{input.data.object.id}}",
"planName": "{{input.data.object.items.data.[0].plan.nickname}}",
"planAmount": "{{input.data.object.items.data.[0].plan.amount}}",
"interval": "{{input.data.object.items.data.[0].plan.interval}}"
}
}
},
{
"id": "get-stripe-customer",
"type": "action",
"name": "Get Stripe Customer Details",
"config": {
"connector": "stripe",
"action": "getCustomer",
"customerId": "{{steps.extract-customer-data.output.customerId}}"
}
},
{
"id": "create-qb-customer",
"type": "action",
"name": "Create QuickBooks Customer",
"config": {
"connector": "quickbooks",
"action": "createCustomer",
"DisplayName": "{{steps.get-stripe-customer.output.name}}",
"PrimaryEmailAddr": {
"Address": "{{steps.get-stripe-customer.output.email}}"
},
"Notes": "Stripe ID: {{steps.get-stripe-customer.output.id}}"
},
"onError": {
"action": "continue",
"fallback": { "Id": null }
}
},
{
"id": "upsert-hubspot-contact",
"type": "action",
"name": "Create/Update HubSpot Contact",
"config": {
"connector": "hubspot",
"action": "createContact",
"email": "{{steps.get-stripe-customer.output.email}}",
"properties": {
"firstname": "{{steps.get-stripe-customer.output.name | split: ' ' | first}}",
"lastname": "{{steps.get-stripe-customer.output.name | split: ' ' | last}}",
"lifecyclestage": "customer",
"stripe_customer_id": "{{steps.get-stripe-customer.output.id}}",
"subscription_plan": "{{steps.extract-customer-data.output.planName}}"
}
},
"onError": {
"action": "continue",
"fallback": { "id": null }
}
},
{
"id": "send-welcome-email",
"type": "email",
"name": "Send Welcome Email",
"config": {
"action": "send",
"provider": "resend",
"to": "{{steps.get-stripe-customer.output.email}}",
"from": "onboarding@yourcompany.com",
"subject": "Welcome to {{steps.extract-customer-data.output.planName}}!",
"body": {
"html": "Welcome!
Thank you for subscribing. We're excited to have you on board!
"
}
}
},
{
"id": "notify-cs-team",
"type": "slack",
"name": "Notify Customer Success",
"config": {
"action": "sendMessage",
"channel": "#new-customers",
"blocks": [
{
"type": "header",
"text": { "type": "plain_text", "text": "New Customer Signed Up!" }
},
{
"type": "section",
"fields": [
{ "type": "mrkdwn", "text": "*Customer:*\n{{steps.get-stripe-customer.output.name}}" },
{ "type": "mrkdwn", "text": "*Plan:*\n{{steps.extract-customer-data.output.planName}}" }
]
},
{
"type": "actions",
"elements": [
{
"type": "button",
"text": { "type": "plain_text", "text": "View in Stripe" },
"url": "https://dashboard.stripe.com/customers/{{steps.get-stripe-customer.output.id}}"
}
]
}
]
}
}
]
}
```
## Testing
### 1. Create Test Workflow
```bash
curl -X POST https://workflow.loopfour.ai/api/v1/workflows \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d @workflow.json
```
### 2. Activate Workflow
```bash
curl -X POST https://workflow.loopfour.ai/api/v1/workflows/{workflowId}/activate \
-H "x-api-key: YOUR_API_KEY"
```
### 3. Test with Simulated Webhook
```bash
curl -X POST https://workflow.loopfour.ai/webhooks/stripe/{companyId} \
-H "Content-Type: application/json" \
-H "stripe-signature: test" \
-d '{
"type": "customer.subscription.created",
"data": {
"object": {
"id": "sub_1234567890",
"customer": "cus_1234567890",
"status": "active",
"items": {
"data": [{
"plan": {
"nickname": "Pro Plan",
"amount": 9900,
"interval": "month"
}
}]
}
}
}
}'
```
### 4. Verify Results
| System | What to Verify |
|--------|---------------|
| QuickBooks | New customer created with Stripe ID in notes |
| HubSpot | Contact created with lifecycle stage = customer |
| Email | Welcome email received |
| Slack | Notification in #new-customers |
### 5. End-to-End Test
1. Create a test product and price in Stripe
2. Use Stripe test mode to create a subscription
3. Watch the workflow execute automatically
4. Verify all systems updated
## Error Handling
### Graceful Degradation
The workflow uses `onError: { action: "continue" }` for non-critical steps so the workflow continues even if one system fails:
```json
{
"id": "create-qb-customer",
"config": { ... },
"onError": {
"action": "continue",
"fallback": { "Id": null }
}
}
```
### Notify on Partial Failure
Add a check at the end:
```json
{
"id": "check-all-succeeded",
"type": "condition",
"config": {
"if": "{{steps.create-qb-customer.output.Id && steps.upsert-hubspot-contact.output.id}}",
"then": "end",
"else": "notify-partial-failure"
}
},
{
"id": "notify-partial-failure",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "#ops-alerts",
"text": ":warning: Customer onboarding partially failed for {{steps.get-stripe-customer.output.email}}. Check QuickBooks: {{#unless steps.create-qb-customer.output.Id}}FAILED{{/unless}}, HubSpot: {{#unless steps.upsert-hubspot-contact.output.id}}FAILED{{/unless}}"
}
}
```
### Handle Duplicate Customers
Check if customer already exists:
```json
{
"id": "check-qb-customer-exists",
"type": "action",
"config": {
"connector": "quickbooks",
"action": "findCustomerByEmail",
"email": "{{steps.get-stripe-customer.output.email}}"
}
},
{
"id": "decide-create-or-skip",
"type": "condition",
"config": {
"if": "{{steps.check-qb-customer-exists.output.QueryResponse.Customer.length > 0}}",
"then": "skip-qb-creation",
"else": "create-qb-customer"
}
}
```
## Variations and Extensions
### Plan-Specific Onboarding
Different onboarding flows for different plans:
```json
{
"id": "route-by-plan",
"type": "condition",
"config": {
"if": "{{steps.extract-customer-data.output.planName === 'Enterprise'}}",
"then": "enterprise-onboarding",
"else": {
"if": "{{steps.extract-customer-data.output.planName === 'Pro'}}",
"then": "pro-onboarding",
"else": "basic-onboarding"
}
}
}
```
### Create NetSuite Customer Instead
For enterprise companies using NetSuite:
```json
{
"id": "create-netsuite-customer",
"type": "action",
"config": {
"connector": "netsuite",
"action": "createCustomer",
"companyName": "{{steps.get-stripe-customer.output.metadata.company_name}}",
"email": "{{steps.get-stripe-customer.output.email}}",
"subsidiary": { "id": "1" },
"customFields": {
"custentity_stripe_id": "{{steps.get-stripe-customer.output.id}}"
}
}
}
```
### Scheduled Follow-up Email
Send a check-in email 7 days after signup:
```json
{
"id": "schedule-followup",
"type": "email",
"config": {
"action": "schedule",
"provider": "resend",
"to": "{{steps.get-stripe-customer.output.email}}",
"subject": "How's it going with {{steps.extract-customer-data.output.planName}}?",
"body": {
"html": "Hi {{steps.get-stripe-customer.output.name}},
You've been using {{steps.extract-customer-data.output.planName}} for a week now. How's it going?
If you have any questions or need help, just reply to this email!
"
},
"send_at": "{{now | dateAdd: 7, 'days' | date: '%Y-%m-%dT%H:%M:%SZ'}}"
}
}
```
### Create Salesforce Account and Contact
For Salesforce users:
```json
{
"id": "create-sf-account",
"type": "action",
"config": {
"connector": "salesforce",
"action": "createOpportunity",
"Name": "{{steps.get-stripe-customer.output.metadata.company_name}} - New Subscription",
"StageName": "Closed Won",
"CloseDate": "{{now | date: '%Y-%m-%d'}}",
"Amount": "{{steps.extract-customer-data.output.planAmount | divided_by: 100}}"
}
},
{
"id": "create-sf-contact",
"type": "action",
"config": {
"connector": "salesforce",
"action": "createContact",
"FirstName": "{{steps.get-stripe-customer.output.name | split: ' ' | first}}",
"LastName": "{{steps.get-stripe-customer.output.name | split: ' ' | last}}",
"Email": "{{steps.get-stripe-customer.output.email}}",
"Stripe_Customer_ID__c": "{{steps.get-stripe-customer.output.id}}"
}
}
```
### Assign CSM Based on Plan
Route high-value customers to senior CSMs:
```json
{
"id": "determine-csm",
"type": "transform",
"config": {
"operation": "map",
"data": {
"csmEmail": "{{#if (gt steps.extract-customer-data.output.planAmount 50000)}}senior-csm@company.com{{else if (gt steps.extract-customer-data.output.planAmount 10000)}}csm@company.com{{else}}onboarding@company.com{{/if}}",
"csmSlackId": "{{#if (gt steps.extract-customer-data.output.planAmount 50000)}}U12345{{else}}U67890{{/if}}"
}
}
},
{
"id": "notify-assigned-csm",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "@{{steps.determine-csm.output.csmSlackId}}",
"text": "You've been assigned a new customer: {{steps.get-stripe-customer.output.name}} ({{steps.extract-customer-data.output.planName}})"
}
}
```
### Trial Conversion Variant
Handle trial-to-paid conversion differently:
```json
{
"trigger": {
"type": "webhook",
"provider": "stripe",
"events": ["customer.subscription.updated"],
"filter": {
"data.object.status": { "$eq": "active" },
"data.previous_attributes.status": { "$eq": "trialing" }
}
}
}
```
## Common Issues
| Issue | Cause | Solution |
|-------|-------|----------|
| Duplicate customers | Same webhook fired twice | Add idempotency check with subscription ID |
| Missing customer name | Stripe customer has no name | Fall back to email prefix |
| QuickBooks sync failed | Customer already exists | Check before create, update instead |
| Email not sent | Invalid email format | Validate email in transform step |
| Wrong plan amount | Amount is in cents | Divide by 100 for display |
## Related Resources
- [Stripe Integration Guide](/docs/integrations/payments/stripe)
- [QuickBooks Integration Guide](/docs/integrations/accounting/quickbooks)
- [HubSpot Integration Guide](/docs/integrations/crm/hubspot)
- [Email Block Reference](/docs/workflows/building-blocks/email-block)
- [Customer Success Use Cases](/docs/use-cases/customer-success)
# Deal Sync (/docs/tutorials/deal-sync)
Automatically create contracts when CRM deals reach the right stage
## Deal Sync Tutorial
Learn how to automatically create and send PandaDoc contracts when HubSpot deals reach the contract stage, eliminating manual document creation and accelerating your sales cycle.
## The Problem
When a sales deal is ready for contract, sales teams typically:
1. Manually log into PandaDoc or another contract system
2. Find the right template and create a new document
3. Copy deal data from the CRM into the contract
4. Add recipients and send for signature
5. Update the CRM with the document link
6. Track signing status manually
This manual process causes:
- **Delayed contracts** - Hours between "ready to sign" and contract sent
- **Data inconsistencies** - Typos, wrong amounts, outdated information
- **Lost deals** - Momentum dies while waiting for paperwork
- **No visibility** - Sales managers can't see contract status at a glance
## The Solution
Build a workflow that automatically:
1. Triggers when a HubSpot deal moves to "Contract Sent" stage
2. Retrieves deal and contact information
3. Creates a contract from a PandaDoc template with deal data
4. Sends the contract for signature
5. Updates the HubSpot deal with the document link
6. Notifies the sales team in Slack
7. (Bonus) Updates the deal when the contract is signed
## What You'll Build
```
HubSpot Deal → Contract Sent Stage
│
▼
┌───────────────────┐
│ Get Deal Details │
└─────────┬─────────┘
│
▼
┌───────────────────┐
│ Get Primary │
│ Contact │
└─────────┬─────────┘
│
▼
┌───────────────────┐
│ Get Company │
│ Details │
└─────────┬─────────┘
│
▼
┌───────────────────┐
│ Create PandaDoc │
│ Contract │
└─────────┬─────────┘
│
▼
┌───────────────────┐
│ Send for │
│ Signature │
└─────────┬─────────┘
│
▼
┌───────────────────┐
│ Update HubSpot │
│ Deal │
└─────────┬─────────┘
│
▼
┌───────────────────┐
│ Notify Sales │
│ in Slack │
└───────────────────┘
```
## Prerequisites
### Required Connections
| Provider | Connection Type | Purpose |
|----------|----------------|---------|
| HubSpot | OAuth via Nango | Receive webhooks, get/update deals |
| PandaDoc | OAuth via Nango | Create and send documents |
| Slack | OAuth via Nango | Team notifications |
### HubSpot Setup
1. **Configure Webhook Subscriptions** in your HubSpot app:
- Subscribe to `deal.propertyChange` events
- Include `dealstage` property in the subscription
2. **Deal Pipeline Stages**: Note your stage IDs
- Go to Settings → Objects → Deals → Pipelines
- Find the internal ID for your "Contract Sent" stage (e.g., `contractsent`)
3. **Custom Properties** (recommended):
- `contract_url` (Single-line text) - To store PandaDoc link
- `contract_status` (Dropdown) - Draft, Sent, Viewed, Signed
### PandaDoc Setup
1. **Create Contract Template**:
- Go to Templates → Create Template
- Design your contract with placeholder fields
- Add tokens for dynamic data (deal amount, company name, etc.)
- Note the template ID from the URL
2. **Configure Tokens** in your template:
- `{{deal_name}}` - Deal/opportunity name
- `{{deal_amount}}` - Contract value
- `{{company_name}}` - Customer company
- `{{contact_name}}` - Signer name
- `{{contact_email}}` - Signer email
## Step-by-Step Implementation
### Step 1: Create the Workflow
Start with the trigger configuration:
```json
{
"name": "Deal → Contract",
"description": "Create and send PandaDoc contract when deal reaches contract stage",
"trigger": {
"type": "webhook",
"provider": "hubspot",
"events": ["deal.propertyChange"],
"filter": {
"propertyName": { "$eq": "dealstage" },
"propertyValue": { "$eq": "contractsent" }
}
},
"steps": []
}
```
**Why this filter?**
- HubSpot sends property change events for any deal update
- We filter to only trigger when `dealstage` changes to `contractsent`
- This prevents duplicate contract creation
### Step 2: Get Deal Details
Retrieve the full deal information:
```json
{
"id": "get-deal",
"type": "action",
"name": "Get Deal Details",
"config": {
"connector": "hubspot",
"action": "getDeal",
"dealId": "{{input.objectId}}",
"properties": [
"dealname",
"amount",
"closedate",
"dealstage",
"pipeline",
"hubspot_owner_id"
],
"associations": ["contacts", "companies"]
}
}
```
**Key properties:**
- `dealname` - The deal/opportunity name
- `amount` - Contract value
- `closedate` - Expected close date
- `associations` - Returns linked contacts and companies
### Step 3: Get Primary Contact
Retrieve the contact who will sign the contract:
```json
{
"id": "get-contact",
"type": "action",
"name": "Get Primary Contact",
"config": {
"connector": "hubspot",
"action": "getContact",
"contactId": "{{steps.get-deal.output.associations.contacts.results.[0].id}}",
"properties": [
"firstname",
"lastname",
"email",
"jobtitle",
"phone"
]
}
}
```
**Output includes:**
- `firstname`, `lastname` - Contact name
- `email` - For contract delivery
- `jobtitle` - For contract personalization
### Step 4: Get Company Details
Retrieve the associated company:
```json
{
"id": "get-company",
"type": "action",
"name": "Get Company Details",
"config": {
"connector": "hubspot",
"action": "getCompany",
"companyId": "{{steps.get-deal.output.associations.companies.results.[0].id}}",
"properties": [
"name",
"domain",
"address",
"city",
"state",
"zip",
"country"
]
}
}
```
### Step 5: Create PandaDoc Document
Create the contract from your template:
```json
{
"id": "create-contract",
"type": "action",
"name": "Create Contract from Template",
"config": {
"connector": "pandadoc",
"action": "createDocument",
"templateId": "YOUR_TEMPLATE_ID",
"name": "Contract - {{steps.get-deal.output.properties.dealname}}",
"recipients": [
{
"email": "{{steps.get-contact.output.properties.email}}",
"first_name": "{{steps.get-contact.output.properties.firstname}}",
"last_name": "{{steps.get-contact.output.properties.lastname}}",
"role": "Signer"
}
],
"tokens": [
{
"name": "deal_name",
"value": "{{steps.get-deal.output.properties.dealname}}"
},
{
"name": "deal_amount",
"value": "{{steps.get-deal.output.properties.amount}}"
},
{
"name": "company_name",
"value": "{{steps.get-company.output.properties.name}}"
},
{
"name": "contact_name",
"value": "{{steps.get-contact.output.properties.firstname}} {{steps.get-contact.output.properties.lastname}}"
},
{
"name": "contact_title",
"value": "{{steps.get-contact.output.properties.jobtitle}}"
},
{
"name": "effective_date",
"value": "{{now | date: '%B %d, %Y'}}"
}
],
"metadata": {
"hubspot_deal_id": "{{input.objectId}}",
"hubspot_company_id": "{{steps.get-company.output.id}}"
}
}
}
```
**Key configuration:**
- `templateId` - Your PandaDoc template ID
- `recipients` - Who needs to sign
- `tokens` - Dynamic values to populate in the contract
- `metadata` - Track the source deal
### Step 6: Wait for Document Processing
PandaDoc needs time to process the document:
```json
{
"id": "wait-for-document",
"type": "delay",
"name": "Wait for Document Processing",
"config": {
"duration": 5,
"unit": "seconds"
}
}
```
### Step 7: Send Document for Signature
Send the contract to the recipient:
```json
{
"id": "send-contract",
"type": "action",
"name": "Send Contract for Signature",
"config": {
"connector": "pandadoc",
"action": "sendDocument",
"documentId": "{{steps.create-contract.output.id}}",
"message": "Hi {{steps.get-contact.output.properties.firstname}},\n\nPlease find attached the contract for {{steps.get-deal.output.properties.dealname}}.\n\nPlease review and sign at your earliest convenience.\n\nThank you!",
"subject": "Contract Ready: {{steps.get-deal.output.properties.dealname}}"
}
}
```
### Step 8: Create Signing Link
Generate a direct signing link:
```json
{
"id": "create-signing-link",
"type": "action",
"name": "Create Signing Link",
"config": {
"connector": "pandadoc",
"action": "createDocumentLink",
"documentId": "{{steps.create-contract.output.id}}",
"recipientEmail": "{{steps.get-contact.output.properties.email}}",
"lifetime": 604800
}
}
```
**Parameters:**
- `lifetime` - Link validity in seconds (604800 = 7 days)
### Step 9: Update HubSpot Deal
Update the deal with contract information:
```json
{
"id": "update-deal",
"type": "action",
"name": "Update Deal with Contract Link",
"config": {
"connector": "hubspot",
"action": "updateDeal",
"dealId": "{{input.objectId}}",
"properties": {
"contract_url": "{{steps.create-signing-link.output.link}}",
"contract_status": "Sent",
"notes_last_updated": "Contract sent to {{steps.get-contact.output.properties.email}} on {{now | date: '%Y-%m-%d %H:%M'}}"
}
}
}
```
### Step 10: Notify Sales Team
Send a Slack notification:
```json
{
"id": "notify-sales",
"type": "slack",
"name": "Notify Sales Team",
"config": {
"action": "sendMessage",
"channel": "#sales-contracts",
"blocks": [
{
"type": "header",
"text": {
"type": "plain_text",
"text": "Contract Sent for Signature"
}
},
{
"type": "section",
"fields": [
{
"type": "mrkdwn",
"text": "*Deal:*\n{{steps.get-deal.output.properties.dealname}}"
},
{
"type": "mrkdwn",
"text": "*Value:*\n${{steps.get-deal.output.properties.amount}}"
},
{
"type": "mrkdwn",
"text": "*Company:*\n{{steps.get-company.output.properties.name}}"
},
{
"type": "mrkdwn",
"text": "*Signer:*\n{{steps.get-contact.output.properties.firstname}} {{steps.get-contact.output.properties.lastname}}"
}
]
},
{
"type": "context",
"elements": [
{
"type": "mrkdwn",
"text": "Sent to: {{steps.get-contact.output.properties.email}}"
}
]
},
{
"type": "actions",
"elements": [
{
"type": "button",
"text": {
"type": "plain_text",
"text": "View in PandaDoc"
},
"url": "https://app.pandadoc.com/documents/{{steps.create-contract.output.id}}"
},
{
"type": "button",
"text": {
"type": "plain_text",
"text": "View Deal"
},
"url": "https://app.hubspot.com/contacts/YOUR_PORTAL_ID/deal/{{input.objectId}}"
}
]
}
]
}
}
```
## Complete Workflow
Here's the complete workflow JSON:
```json
{
"name": "Deal → Contract",
"description": "Create and send PandaDoc contract when deal reaches contract stage",
"trigger": {
"type": "webhook",
"provider": "hubspot",
"events": ["deal.propertyChange"],
"filter": {
"propertyName": { "$eq": "dealstage" },
"propertyValue": { "$eq": "contractsent" }
}
},
"steps": [
{
"id": "get-deal",
"type": "action",
"name": "Get Deal Details",
"config": {
"connector": "hubspot",
"action": "getDeal",
"dealId": "{{input.objectId}}",
"properties": ["dealname", "amount", "closedate", "dealstage", "pipeline"],
"associations": ["contacts", "companies"]
}
},
{
"id": "get-contact",
"type": "action",
"name": "Get Primary Contact",
"config": {
"connector": "hubspot",
"action": "getContact",
"contactId": "{{steps.get-deal.output.associations.contacts.results.[0].id}}",
"properties": ["firstname", "lastname", "email", "jobtitle", "phone"]
}
},
{
"id": "get-company",
"type": "action",
"name": "Get Company Details",
"config": {
"connector": "hubspot",
"action": "getCompany",
"companyId": "{{steps.get-deal.output.associations.companies.results.[0].id}}",
"properties": ["name", "domain", "address", "city", "state", "zip"]
}
},
{
"id": "create-contract",
"type": "action",
"name": "Create Contract from Template",
"config": {
"connector": "pandadoc",
"action": "createDocument",
"templateId": "YOUR_TEMPLATE_ID",
"name": "Contract - {{steps.get-deal.output.properties.dealname}}",
"recipients": [
{
"email": "{{steps.get-contact.output.properties.email}}",
"first_name": "{{steps.get-contact.output.properties.firstname}}",
"last_name": "{{steps.get-contact.output.properties.lastname}}",
"role": "Signer"
}
],
"tokens": [
{ "name": "deal_name", "value": "{{steps.get-deal.output.properties.dealname}}" },
{ "name": "deal_amount", "value": "{{steps.get-deal.output.properties.amount}}" },
{ "name": "company_name", "value": "{{steps.get-company.output.properties.name}}" },
{ "name": "contact_name", "value": "{{steps.get-contact.output.properties.firstname}} {{steps.get-contact.output.properties.lastname}}" }
],
"metadata": {
"hubspot_deal_id": "{{input.objectId}}"
}
}
},
{
"id": "wait-for-document",
"type": "delay",
"name": "Wait for Document Processing",
"config": {
"duration": 5,
"unit": "seconds"
}
},
{
"id": "send-contract",
"type": "action",
"name": "Send Contract for Signature",
"config": {
"connector": "pandadoc",
"action": "sendDocument",
"documentId": "{{steps.create-contract.output.id}}",
"message": "Please review and sign the attached contract.",
"subject": "Contract Ready: {{steps.get-deal.output.properties.dealname}}"
}
},
{
"id": "create-signing-link",
"type": "action",
"name": "Create Signing Link",
"config": {
"connector": "pandadoc",
"action": "createDocumentLink",
"documentId": "{{steps.create-contract.output.id}}",
"recipientEmail": "{{steps.get-contact.output.properties.email}}",
"lifetime": 604800
}
},
{
"id": "update-deal",
"type": "action",
"name": "Update Deal with Contract Link",
"config": {
"connector": "hubspot",
"action": "updateDeal",
"dealId": "{{input.objectId}}",
"properties": {
"contract_url": "{{steps.create-signing-link.output.link}}",
"contract_status": "Sent"
}
}
},
{
"id": "notify-sales",
"type": "slack",
"name": "Notify Sales Team",
"config": {
"action": "sendMessage",
"channel": "#sales-contracts",
"blocks": [
{
"type": "header",
"text": { "type": "plain_text", "text": "Contract Sent for Signature" }
},
{
"type": "section",
"fields": [
{ "type": "mrkdwn", "text": "*Deal:*\n{{steps.get-deal.output.properties.dealname}}" },
{ "type": "mrkdwn", "text": "*Value:*\n${{steps.get-deal.output.properties.amount}}" }
]
},
{
"type": "actions",
"elements": [
{
"type": "button",
"text": { "type": "plain_text", "text": "View in PandaDoc" },
"url": "https://app.pandadoc.com/documents/{{steps.create-contract.output.id}}"
}
]
}
]
}
}
]
}
```
## Testing
### 1. Create Test Workflow
```bash
curl -X POST https://workflow.loopfour.ai/api/v1/workflows \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d @workflow.json
```
### 2. Activate Workflow
```bash
curl -X POST https://workflow.loopfour.ai/api/v1/workflows/{workflowId}/activate \
-H "x-api-key: YOUR_API_KEY"
```
### 3. Test with Simulated Webhook
```bash
curl -X POST https://workflow.loopfour.ai/webhooks/hubspot/{companyId} \
-H "Content-Type: application/json" \
-d '{
"objectId": 12345678,
"propertyName": "dealstage",
"propertyValue": "contractsent",
"subscriptionType": "deal.propertyChange"
}'
```
### 4. Verify Results
| System | What to Verify |
|--------|---------------|
| PandaDoc | New document created and sent |
| HubSpot | Deal updated with contract_url |
| Slack | Notification in #sales-contracts |
| Recipient Email | Contract email received |
### 5. End-to-End Test
1. Create a test deal in HubSpot with a contact and company
2. Move the deal to "Contract Sent" stage
3. Watch the workflow execute
4. Verify contract created in PandaDoc
5. Check recipient received signing request
## Bonus: Handle Contract Signed
Create a second workflow that triggers when the contract is signed:
```json
{
"name": "Contract Signed → Close Deal",
"trigger": {
"type": "webhook",
"provider": "pandadoc",
"events": ["document_state_changed"],
"filter": {
"data.status": { "$eq": "document.completed" }
}
},
"steps": [
{
"id": "get-document",
"type": "action",
"config": {
"connector": "pandadoc",
"action": "getDocument",
"documentId": "{{input.data.id}}"
}
},
{
"id": "update-deal-closed",
"type": "action",
"config": {
"connector": "hubspot",
"action": "updateDeal",
"dealId": "{{steps.get-document.output.metadata.hubspot_deal_id}}",
"properties": {
"dealstage": "closedwon",
"contract_status": "Signed"
}
}
},
{
"id": "download-signed-contract",
"type": "action",
"config": {
"connector": "pandadoc",
"action": "downloadDocument",
"documentId": "{{input.data.id}}"
}
},
{
"id": "notify-deal-won",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "#sales-wins",
"text": ":tada: Contract signed! Deal {{steps.get-document.output.name}} is now Closed Won!"
}
}
]
}
```
## Error Handling
### Handle Missing Contact
```json
{
"id": "check-contact-exists",
"type": "condition",
"config": {
"if": "{{steps.get-deal.output.associations.contacts.results.length > 0}}",
"then": "get-contact",
"else": "notify-missing-contact"
}
}
```
### Handle PandaDoc Errors
```json
{
"id": "create-contract",
"type": "action",
"config": { ... },
"onError": {
"action": "goto",
"step": "notify-contract-error"
}
}
```
### Notify on Failure
```json
{
"id": "notify-contract-error",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "#sales-alerts",
"text": ":warning: Failed to create contract for deal {{steps.get-deal.output.properties.dealname}}. Error: {{error.message}}"
}
}
```
## Variations and Extensions
### Multiple Signers
Add a counter-signer from your company:
```json
{
"recipients": [
{
"email": "{{steps.get-contact.output.properties.email}}",
"first_name": "{{steps.get-contact.output.properties.firstname}}",
"last_name": "{{steps.get-contact.output.properties.lastname}}",
"role": "Customer",
"signing_order": 1
},
{
"email": "sales@yourcompany.com",
"first_name": "Sales",
"last_name": "Team",
"role": "Company",
"signing_order": 2
}
]
}
```
### Different Templates by Deal Size
Use conditional logic to select templates:
```json
{
"id": "select-template",
"type": "transform",
"config": {
"operation": "map",
"data": {
"templateId": "{{#if (gt steps.get-deal.output.properties.amount 100000)}}ENTERPRISE_TEMPLATE_ID{{else if (gt steps.get-deal.output.properties.amount 25000)}}STANDARD_TEMPLATE_ID{{else}}BASIC_TEMPLATE_ID{{/if}}"
}
}
}
```
### Salesforce Variant
Use Salesforce instead of HubSpot:
```json
{
"trigger": {
"type": "webhook",
"provider": "salesforce",
"events": ["opportunity.updated"],
"filter": {
"StageName": { "$eq": "Contract" }
}
},
"steps": [
{
"id": "get-opportunity",
"type": "action",
"config": {
"connector": "salesforce",
"action": "getOpportunity",
"opportunityId": "{{input.payload.Id}}"
}
},
{
"id": "get-contact",
"type": "action",
"config": {
"connector": "salesforce",
"action": "query",
"query": "SELECT Id, Name, Email FROM Contact WHERE AccountId = '{{input.payload.AccountId}}' LIMIT 1"
}
}
]
}
```
### Add Legal Review Step
For high-value deals, add a legal review step:
```json
{
"id": "check-legal-review",
"type": "condition",
"config": {
"if": "{{steps.get-deal.output.properties.amount > 500000}}",
"then": "request-legal-review",
"else": "send-contract"
}
},
{
"id": "request-legal-review",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "#legal-review",
"blocks": [
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "*Legal Review Required*\n\nDeal: {{steps.get-deal.output.properties.dealname}}\nAmount: ${{steps.get-deal.output.properties.amount}}"
}
},
{
"type": "actions",
"elements": [
{
"type": "button",
"text": { "type": "plain_text", "text": "Approve" },
"style": "primary",
"action_id": "approve_contract_{{input.objectId}}"
},
{
"type": "button",
"text": { "type": "plain_text", "text": "Reject" },
"style": "danger",
"action_id": "reject_contract_{{input.objectId}}"
}
]
}
]
}
}
```
## Common Issues
| Issue | Cause | Solution |
|-------|-------|----------|
| Document not created | Invalid template ID | Verify template ID in PandaDoc |
| Missing recipient | No contact on deal | Add validation step, require contact |
| Duplicate contracts | Webhook retries | Add idempotency check using deal ID |
| Wrong data in contract | Incorrect token names | Match template tokens exactly |
| Send failed | Document still processing | Increase delay or poll for status |
## Related Resources
- [HubSpot Integration Guide](/docs/integrations/crm/hubspot)
- [PandaDoc Integration Guide](/docs/integrations/documents/pandadoc)
- [Slack Block Reference](/docs/workflows/building-blocks/slack-block)
- [Conditional Steps](/docs/workflows/steps/conditions)
- [Sales Ops Use Cases](/docs/use-cases/sales-ops)
# Invoice Automation (/docs/tutorials/invoice-automation)
Automatically create and send invoices when CRM deals close
## Invoice Automation Tutorial
Learn how to automatically create invoices in Stripe when Salesforce opportunities close, eliminating manual data entry and accelerating your revenue cycle.
## The Problem
When a sales deal closes, finance teams typically:
1. Wait for sales to notify them (often via email or spreadsheet)
2. Manually look up the customer in Stripe
3. Create an invoice with the correct line items
4. Send the invoice to the customer
5. Update the CRM opportunity with invoice details
This manual process causes:
- **Delayed invoicing** - Hours or days between deal close and invoice sent
- **Data entry errors** - Wrong amounts, typos in customer details
- **Missing invoices** - Deals that slip through the cracks
- **No audit trail** - Hard to track what was invoiced and when
## The Solution
Build a workflow that automatically:
1. Triggers instantly when a Salesforce opportunity closes as "Won"
2. Finds or creates the customer in Stripe
3. Creates an invoice with line items from the opportunity
4. Sends the invoice immediately
5. Updates the Salesforce opportunity with the invoice URL
6. Notifies the sales and finance teams
## What You'll Build
```
Salesforce Opportunity Closes (Won)
│
▼
┌───────────────────┐
│ Get Account Email │
└─────────┬─────────┘
│
▼
┌───────────────────┐
│ Find/Create │
│ Stripe Customer │
└─────────┬─────────┘
│
▼
┌───────────────────┐
│ Create Invoice │
│ with Line Items │
└─────────┬─────────┘
│
▼
┌───────────────────┐
│ Finalize & Send │
│ Invoice │
└─────────┬─────────┘
│
▼
┌───────────────────┐
│ Update Salesforce │
│ Opportunity │
└─────────┬─────────┘
│
▼
┌───────────────────┐
│ Notify Team │
│ in Slack │
└───────────────────┘
```
## Prerequisites
### Required Connections
| Provider | Connection Type | Purpose |
|----------|----------------|---------|
| Salesforce | OAuth via Nango | Receive webhooks, update opportunities |
| Stripe | OAuth via Nango | Create customers, invoices |
| Slack | OAuth via Nango | Team notifications |
### Salesforce Setup
1. **Enable Change Data Capture (CDC)** for the Opportunity object:
- Setup → Integrations → Change Data Capture
- Select "Opportunity" and move to Selected Entities
- Save
2. **Custom Fields** (optional but recommended):
- `Invoice_URL__c` (URL) - To store the Stripe invoice link
- `Invoice_Status__c` (Picklist) - Draft, Sent, Paid, Overdue
### Stripe Setup
Ensure your Stripe account has:
- Products/prices configured for your offerings
- Tax settings configured (if applicable)
- Invoice customization (logo, footer, etc.)
## Step-by-Step Implementation
### Step 1: Create the Workflow
Start with the basic workflow structure:
```json
{
"name": "Deal Close → Invoice",
"description": "Automatically create and send Stripe invoice when Salesforce opportunity closes won",
"trigger": {
"type": "webhook",
"provider": "salesforce",
"events": ["opportunity.updated"],
"filter": {
"StageName": { "$eq": "Closed Won" },
"IsClosed": { "$eq": true },
"IsWon": { "$eq": true }
}
},
"steps": []
}
```
**Why this filter?**
- We only want opportunities that just closed as "Won"
- The CDC event fires on any update, so we filter for the specific state
- `IsClosed` and `IsWon` ensure we don't process losses
### Step 2: Get Account Details
Retrieve the associated account to get the billing email:
```json
{
"id": "get-account",
"type": "action",
"name": "Get Account Details",
"config": {
"connector": "salesforce",
"action": "getAccount",
"accountId": "{{input.payload.AccountId}}"
}
}
```
**Output includes:**
- `Name` - Company name
- `BillingStreet`, `BillingCity`, `BillingState`, `BillingPostalCode`, `BillingCountry`
- Custom fields like `Billing_Email__c`
### Step 3: Find or Create Stripe Customer
Check if the customer exists in Stripe, create if not:
```json
{
"id": "find-stripe-customer",
"type": "action",
"name": "Find Stripe Customer",
"config": {
"connector": "stripe",
"action": "listCustomers",
"email": "{{steps.get-account.output.Billing_Email__c}}"
}
}
```
Then conditionally create:
```json
{
"id": "create-stripe-customer",
"type": "action",
"name": "Create Stripe Customer",
"condition": "{{steps.find-stripe-customer.output.data.length === 0}}",
"config": {
"connector": "stripe",
"action": "createCustomer",
"email": "{{steps.get-account.output.Billing_Email__c}}",
"name": "{{steps.get-account.output.Name}}",
"metadata": {
"salesforce_account_id": "{{steps.get-account.output.Id}}",
"salesforce_opportunity_id": "{{input.payload.Id}}"
},
"address": {
"line1": "{{steps.get-account.output.BillingStreet}}",
"city": "{{steps.get-account.output.BillingCity}}",
"state": "{{steps.get-account.output.BillingState}}",
"postal_code": "{{steps.get-account.output.BillingPostalCode}}",
"country": "{{steps.get-account.output.BillingCountry}}"
}
}
}
```
### Step 4: Resolve Customer ID
Use a transform to get the customer ID regardless of which path was taken:
```json
{
"id": "resolve-customer",
"type": "transform",
"name": "Get Customer ID",
"config": {
"operation": "map",
"data": {
"customerId": "{{#if steps.create-stripe-customer.output.id}}{{steps.create-stripe-customer.output.id}}{{else}}{{steps.find-stripe-customer.output.data.[0].id}}{{/if}}"
}
}
}
```
### Step 5: Create the Invoice
Create the invoice with line items from the opportunity:
```json
{
"id": "create-invoice",
"type": "action",
"name": "Create Stripe Invoice",
"config": {
"connector": "stripe",
"action": "createInvoice",
"customer": "{{steps.resolve-customer.output.customerId}}",
"collection_method": "send_invoice",
"days_until_due": 30,
"metadata": {
"salesforce_opportunity_id": "{{input.payload.Id}}",
"salesforce_opportunity_name": "{{input.payload.Name}}"
}
}
}
```
### Step 6: Add Line Items
Add line items based on opportunity products or the total amount:
```json
{
"id": "add-line-item",
"type": "action",
"name": "Add Invoice Line Item",
"config": {
"connector": "stripe",
"action": "createInvoiceItem",
"customer": "{{steps.resolve-customer.output.customerId}}",
"invoice": "{{steps.create-invoice.output.id}}",
"description": "{{input.payload.Name}}",
"amount": "{{input.payload.Amount | multiply: 100}}",
"currency": "usd"
}
}
```
**Note:** Stripe amounts are in cents, so we multiply by 100.
### Step 7: Finalize and Send Invoice
Finalize the draft invoice and send it:
```json
{
"id": "finalize-invoice",
"type": "action",
"name": "Finalize Invoice",
"config": {
"connector": "stripe",
"action": "finalizeInvoice",
"invoiceId": "{{steps.create-invoice.output.id}}"
}
}
```
```json
{
"id": "send-invoice",
"type": "action",
"name": "Send Invoice",
"config": {
"connector": "stripe",
"action": "sendInvoice",
"invoiceId": "{{steps.create-invoice.output.id}}"
}
}
```
### Step 8: Update Salesforce Opportunity
Update the opportunity with the invoice URL:
```json
{
"id": "update-opportunity",
"type": "action",
"name": "Update Opportunity with Invoice",
"config": {
"connector": "salesforce",
"action": "updateOpportunity",
"opportunityId": "{{input.payload.Id}}",
"fields": {
"Invoice_URL__c": "{{steps.send-invoice.output.hosted_invoice_url}}",
"Invoice_Status__c": "Sent",
"Description": "{{input.payload.Description}}\n\n---\nInvoice sent automatically on {{now | date: '%Y-%m-%d'}}"
}
}
}
```
### Step 9: Notify Team in Slack
Send a notification to your finance channel:
```json
{
"id": "notify-slack",
"type": "slack",
"name": "Notify Finance Team",
"config": {
"action": "sendMessage",
"channel": "#finance-notifications",
"blocks": [
{
"type": "header",
"text": {
"type": "plain_text",
"text": "Invoice Sent"
}
},
{
"type": "section",
"fields": [
{
"type": "mrkdwn",
"text": "*Opportunity:*\n{{input.payload.Name}}"
},
{
"type": "mrkdwn",
"text": "*Amount:*\n${{input.payload.Amount | number_format: 2}}"
},
{
"type": "mrkdwn",
"text": "*Customer:*\n{{steps.get-account.output.Name}}"
},
{
"type": "mrkdwn",
"text": "*Invoice #:*\n{{steps.send-invoice.output.number}}"
}
]
},
{
"type": "actions",
"elements": [
{
"type": "button",
"text": {
"type": "plain_text",
"text": "View Invoice"
},
"url": "{{steps.send-invoice.output.hosted_invoice_url}}"
},
{
"type": "button",
"text": {
"type": "plain_text",
"text": "View in Salesforce"
},
"url": "https://yourinstance.salesforce.com/{{input.payload.Id}}"
}
]
}
]
}
}
```
## Complete Workflow
Here's the complete workflow JSON:
```json
{
"name": "Deal Close → Invoice",
"description": "Automatically create and send Stripe invoice when Salesforce opportunity closes won",
"trigger": {
"type": "webhook",
"provider": "salesforce",
"events": ["opportunity.updated"],
"filter": {
"StageName": { "$eq": "Closed Won" },
"IsClosed": { "$eq": true },
"IsWon": { "$eq": true }
}
},
"steps": [
{
"id": "get-account",
"type": "action",
"name": "Get Account Details",
"config": {
"connector": "salesforce",
"action": "getAccount",
"accountId": "{{input.payload.AccountId}}"
}
},
{
"id": "find-stripe-customer",
"type": "action",
"name": "Find Stripe Customer",
"config": {
"connector": "stripe",
"action": "listCustomers",
"email": "{{steps.get-account.output.Billing_Email__c}}"
}
},
{
"id": "create-stripe-customer",
"type": "action",
"name": "Create Stripe Customer",
"condition": "{{steps.find-stripe-customer.output.data.length === 0}}",
"config": {
"connector": "stripe",
"action": "createCustomer",
"email": "{{steps.get-account.output.Billing_Email__c}}",
"name": "{{steps.get-account.output.Name}}",
"metadata": {
"salesforce_account_id": "{{steps.get-account.output.Id}}",
"salesforce_opportunity_id": "{{input.payload.Id}}"
},
"address": {
"line1": "{{steps.get-account.output.BillingStreet}}",
"city": "{{steps.get-account.output.BillingCity}}",
"state": "{{steps.get-account.output.BillingState}}",
"postal_code": "{{steps.get-account.output.BillingPostalCode}}",
"country": "{{steps.get-account.output.BillingCountry}}"
}
}
},
{
"id": "resolve-customer",
"type": "transform",
"name": "Get Customer ID",
"config": {
"operation": "map",
"data": {
"customerId": "{{#if steps.create-stripe-customer.output.id}}{{steps.create-stripe-customer.output.id}}{{else}}{{steps.find-stripe-customer.output.data.[0].id}}{{/if}}"
}
}
},
{
"id": "create-invoice",
"type": "action",
"name": "Create Stripe Invoice",
"config": {
"connector": "stripe",
"action": "createInvoice",
"customer": "{{steps.resolve-customer.output.customerId}}",
"collection_method": "send_invoice",
"days_until_due": 30,
"metadata": {
"salesforce_opportunity_id": "{{input.payload.Id}}",
"salesforce_opportunity_name": "{{input.payload.Name}}"
}
}
},
{
"id": "add-line-item",
"type": "action",
"name": "Add Invoice Line Item",
"config": {
"connector": "stripe",
"action": "createInvoiceItem",
"customer": "{{steps.resolve-customer.output.customerId}}",
"invoice": "{{steps.create-invoice.output.id}}",
"description": "{{input.payload.Name}}",
"amount": "{{input.payload.Amount | multiply: 100}}",
"currency": "usd"
}
},
{
"id": "finalize-invoice",
"type": "action",
"name": "Finalize Invoice",
"config": {
"connector": "stripe",
"action": "finalizeInvoice",
"invoiceId": "{{steps.create-invoice.output.id}}"
}
},
{
"id": "send-invoice",
"type": "action",
"name": "Send Invoice",
"config": {
"connector": "stripe",
"action": "sendInvoice",
"invoiceId": "{{steps.create-invoice.output.id}}"
}
},
{
"id": "update-opportunity",
"type": "action",
"name": "Update Opportunity with Invoice",
"config": {
"connector": "salesforce",
"action": "updateOpportunity",
"opportunityId": "{{input.payload.Id}}",
"fields": {
"Invoice_URL__c": "{{steps.send-invoice.output.hosted_invoice_url}}",
"Invoice_Status__c": "Sent"
}
}
},
{
"id": "notify-slack",
"type": "slack",
"name": "Notify Finance Team",
"config": {
"action": "sendMessage",
"channel": "#finance-notifications",
"blocks": [
{
"type": "header",
"text": {
"type": "plain_text",
"text": "Invoice Sent"
}
},
{
"type": "section",
"fields": [
{
"type": "mrkdwn",
"text": "*Opportunity:*\n{{input.payload.Name}}"
},
{
"type": "mrkdwn",
"text": "*Amount:*\n${{input.payload.Amount}}"
}
]
},
{
"type": "actions",
"elements": [
{
"type": "button",
"text": {
"type": "plain_text",
"text": "View Invoice"
},
"url": "{{steps.send-invoice.output.hosted_invoice_url}}"
}
]
}
]
}
}
]
}
```
## Testing
### 1. Create Test Workflow
```bash
curl -X POST https://workflow.loopfour.ai/api/v1/workflows \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d @workflow.json
```
### 2. Activate Workflow
```bash
curl -X POST https://workflow.loopfour.ai/api/v1/workflows/{workflowId}/activate \
-H "x-api-key: YOUR_API_KEY"
```
### 3. Test with Simulated Webhook
```bash
curl -X POST https://workflow.loopfour.ai/webhooks/salesforce/{companyId} \
-H "Content-Type: application/json" \
-d '{
"payload": {
"Id": "006XXXXXXXXXXXXXXX",
"Name": "Test Opportunity - Enterprise Plan",
"Amount": 50000,
"StageName": "Closed Won",
"IsClosed": true,
"IsWon": true,
"AccountId": "001XXXXXXXXXXXXXXX"
}
}'
```
### 4. Verify Results
Check each system:
| System | What to Verify |
|--------|---------------|
| Stripe Dashboard | New customer created, invoice sent |
| Salesforce | Opportunity updated with Invoice_URL__c |
| Slack | Notification in #finance-notifications |
| Workflow Runs | Run completed successfully |
### 5. End-to-End Test
For a real test:
1. Create a test opportunity in Salesforce
2. Move it through stages to "Closed Won"
3. Watch the workflow execute in real-time
4. Verify all systems updated correctly
## Error Handling
### Handle Missing Customer Email
```json
{
"id": "validate-email",
"type": "condition",
"name": "Validate Email Exists",
"config": {
"if": "{{steps.get-account.output.Billing_Email__c}}",
"then": "continue",
"else": "notify-missing-email"
}
}
```
### Handle Stripe API Errors
```json
{
"id": "create-invoice",
"type": "action",
"config": { ... },
"onError": {
"action": "goto",
"step": "notify-error"
}
}
```
### Notify on Failure
```json
{
"id": "notify-error",
"type": "slack",
"name": "Notify Invoice Error",
"config": {
"action": "sendMessage",
"channel": "#finance-alerts",
"text": ":warning: Failed to create invoice for opportunity {{input.payload.Name}}. Error: {{error.message}}"
}
}
```
## Variations and Extensions
### Multi-Currency Support
Add currency detection based on account country:
```json
{
"id": "determine-currency",
"type": "transform",
"config": {
"operation": "map",
"data": {
"currency": "{{#if (eq steps.get-account.output.BillingCountry 'United Kingdom')}}gbp{{else if (eq steps.get-account.output.BillingCountry 'Germany')}}eur{{else}}usd{{/if}}"
}
}
}
```
### Approval for Large Deals
Add an approval step for deals over $100k:
```json
{
"id": "check-approval-needed",
"type": "condition",
"config": {
"if": "{{input.payload.Amount > 100000}}",
"then": "request-approval",
"else": "create-invoice"
}
},
{
"id": "request-approval",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "#finance-approvals",
"blocks": [
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "*Invoice Approval Required*\n\nOpportunity: {{input.payload.Name}}\nAmount: ${{input.payload.Amount}}"
}
},
{
"type": "actions",
"elements": [
{
"type": "button",
"text": { "type": "plain_text", "text": "Approve" },
"style": "primary",
"action_id": "approve_invoice_{{input.payload.Id}}"
},
{
"type": "button",
"text": { "type": "plain_text", "text": "Reject" },
"style": "danger",
"action_id": "reject_invoice_{{input.payload.Id}}"
}
]
}
]
}
}
```
### Multiple Line Items from Opportunity Products
If your opportunities have product line items:
```json
{
"id": "get-opportunity-products",
"type": "action",
"config": {
"connector": "salesforce",
"action": "query",
"query": "SELECT Id, Name, Quantity, UnitPrice, TotalPrice FROM OpportunityLineItem WHERE OpportunityId = '{{input.payload.Id}}'"
}
},
{
"id": "add-line-items",
"type": "loop",
"config": {
"items": "{{steps.get-opportunity-products.output.records}}",
"step": {
"type": "action",
"config": {
"connector": "stripe",
"action": "createInvoiceItem",
"customer": "{{steps.resolve-customer.output.customerId}}",
"invoice": "{{steps.create-invoice.output.id}}",
"description": "{{item.Name}} (Qty: {{item.Quantity}})",
"amount": "{{item.TotalPrice | multiply: 100}}",
"currency": "usd"
}
}
}
}
```
### Add Tax Calculation
Integrate tax calculation for compliant invoicing:
```json
{
"id": "create-invoice",
"type": "action",
"config": {
"connector": "stripe",
"action": "createInvoice",
"customer": "{{steps.resolve-customer.output.customerId}}",
"automatic_tax": {
"enabled": true
}
}
}
```
### HubSpot Variant
Use HubSpot instead of Salesforce:
```json
{
"trigger": {
"type": "webhook",
"provider": "hubspot",
"events": ["deal.propertyChange"],
"filter": {
"propertyName": "dealstage",
"propertyValue": "closedwon"
}
}
}
```
## Common Issues
| Issue | Cause | Solution |
|-------|-------|----------|
| Invoice not created | Missing customer in Stripe | Ensure find-or-create logic works |
| Wrong amount | Currency conversion | Verify amount is in cents for Stripe |
| Duplicate invoices | Webhook retries | Add idempotency key using opportunity ID |
| Missing email | No billing email on account | Add validation step, notify if missing |
## Related Resources
- [Stripe Integration Guide](/docs/integrations/payments/stripe)
- [Salesforce Integration Guide](/docs/integrations/crm/salesforce)
- [Slack Block Reference](/docs/workflows/building-blocks/slack-block)
- [Transform Steps](/docs/workflows/steps/transforms)
- [Finance Team Use Cases](/docs/use-cases/finance-teams)
# Use Cases (/docs/use-cases)
Workflow patterns for different teams
## Use Cases
Discover how different teams use Workflows API.
Use cases describe workflow patterns by team and operating model. They are meant to help you recognize where deterministic automation can remove repeated manual work without hiding important controls. A finance team may care most about invoice intake, reconciliation, approvals, and close evidence. Sales operations may focus on clean handoffs between CRM, contracts, billing, and customer records. Customer success may need onboarding, renewal, and account-health processes that stay synchronized with finance systems.
Each use case should be read as a starting point for scoping. Before building, identify the triggering event, the source-of-truth system, the owner of each exception, and the final record that proves the work happened. Loopfour is most useful when the workflow has clear rules, repeatable inputs, and a known escalation path for ambiguous cases. If the process changes every time, document it first; if it repeats with small variations, it is a strong candidate for automation.
The pages in this section also help teams decide where to begin. Pick a workflow with enough volume to matter, but narrow enough that success can be measured clearly. Good first candidates often have visible queues, repeated copy-and-paste work, frequent handoffs between systems, or exceptions that already follow documented rules. Once the first workflow is stable, expand to adjacent steps that share the same trigger, records, or approval owners.
Invoice automation, payment reconciliation, reporting
Deal management, contract automation, pipeline sync
Onboarding, health monitoring, renewal management
# Customer Success (/docs/use-cases/customer-success)
Workflow patterns for customer success and retention teams
## Customer Success Workflows
Automate onboarding, health monitoring, renewal management, and proactive customer engagement across your customer success stack.
## Why Automate Customer Success?
Customer success teams face unique challenges:
- **Manual onboarding** delays time-to-value for new customers
- **Health score updates** require pulling data from multiple systems
- **Renewal tracking** relies on spreadsheets and calendar reminders
- **Churn signals** often detected too late to intervene
- **NPS and feedback** collection is inconsistent
Workflow automation solves these by:
- Triggering onboarding instantly when subscriptions start
- Calculating health scores automatically from usage data
- Alerting CSMs proactively when accounts need attention
- Standardizing customer communication touchpoints
- Ensuring no renewal falls through the cracks
## Common Workflow Patterns
### Automated Onboarding
**Trigger:** New subscription created in Stripe
**Actions:** Create customer records, send welcome email, notify team
Automatically set up new customers across all systems when they subscribe.
```json
{
"name": "Customer Onboarding",
"trigger": {
"type": "webhook",
"provider": "stripe",
"events": ["customer.subscription.created"]
},
"steps": [
{
"id": "get-customer",
"type": "action",
"config": {
"connector": "stripe",
"action": "getCustomer",
"customerId": "{{input.data.object.customer}}"
}
},
{
"id": "create-qb-customer",
"type": "action",
"config": {
"connector": "quickbooks",
"action": "createCustomer",
"DisplayName": "{{steps.get-customer.output.name}}",
"PrimaryEmailAddr": {
"Address": "{{steps.get-customer.output.email}}"
}
},
"onError": { "action": "continue" }
},
{
"id": "create-hubspot-contact",
"type": "action",
"config": {
"connector": "hubspot",
"action": "createContact",
"email": "{{steps.get-customer.output.email}}",
"properties": {
"firstname": "{{steps.get-customer.output.name | split: ' ' | first}}",
"lastname": "{{steps.get-customer.output.name | split: ' ' | last}}",
"lifecyclestage": "customer",
"stripe_customer_id": "{{steps.get-customer.output.id}}",
"subscription_start_date": "{{now | date: '%Y-%m-%d'}}"
}
}
},
{
"id": "send-welcome-email",
"type": "email",
"config": {
"action": "send",
"provider": "resend",
"to": "{{steps.get-customer.output.email}}",
"from": "success@company.com",
"subject": "Welcome to Company!",
"body": {
"html": "Welcome, {{steps.get-customer.output.name}}!
We're excited to have you on board.
Getting Started
- Complete your setup
- Read our documentation
- Book your onboarding call
"
}
}
},
{
"id": "notify-cs-team",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "#new-customers",
"blocks": [
{
"type": "header",
"text": { "type": "plain_text", "text": "New Customer!" }
},
{
"type": "section",
"fields": [
{ "type": "mrkdwn", "text": "*Name:*\n{{steps.get-customer.output.name}}" },
{ "type": "mrkdwn", "text": "*Email:*\n{{steps.get-customer.output.email}}" },
{ "type": "mrkdwn", "text": "*Plan:*\n{{input.data.object.items.data.[0].plan.nickname}}" },
{ "type": "mrkdwn", "text": "*MRR:*\n${{input.data.object.items.data.[0].plan.amount | divided_by: 100}}" }
]
},
{
"type": "actions",
"elements": [
{
"type": "button",
"text": { "type": "plain_text", "text": "View in Stripe" },
"url": "https://dashboard.stripe.com/customers/{{steps.get-customer.output.id}}"
}
]
}
]
}
}
]
}
```
**Benefits:**
- Customer set up across all systems instantly
- Welcome email sent automatically
- CS team notified with full context
- No manual data entry required
[Full Customer Onboarding Tutorial →](/docs/tutorials/customer-onboarding)
---
### Health Score Monitoring
**Trigger:** Scheduled daily
**Actions:** Calculate usage metrics, update health score, alert on low scores
Automatically calculate and track customer health scores.
```json
{
"name": "Daily Health Score Update",
"trigger": {
"type": "schedule",
"cron": "0 6 * * *"
},
"steps": [
{
"id": "get-active-customers",
"type": "action",
"config": {
"connector": "hubspot",
"action": "searchContacts",
"filter": {
"lifecyclestage": { "$eq": "customer" }
}
}
},
{
"id": "calculate-health-scores",
"type": "loop",
"config": {
"items": "{{steps.get-active-customers.output.results}}",
"step": {
"type": "transform",
"config": {
"operation": "map",
"data": {
"contactId": "{{item.id}}",
"email": "{{item.properties.email}}",
"loginScore": "{{#if (gt item.properties.days_since_login 30)}}0{{else if (gt item.properties.days_since_login 14)}}25{{else if (gt item.properties.days_since_login 7)}}50{{else}}100{{/if}}",
"usageScore": "{{#if (gt item.properties.feature_usage_pct 80)}}100{{else if (gt item.properties.feature_usage_pct 50)}}75{{else if (gt item.properties.feature_usage_pct 25)}}50{{else}}25{{/if}}",
"supportScore": "{{#if (eq item.properties.open_tickets 0)}}100{{else if (lt item.properties.open_tickets 3)}}75{{else}}50{{/if}}",
"healthScore": "{{(loginScore + usageScore + supportScore) / 3}}"
}
}
}
}
},
{
"id": "update-health-scores",
"type": "loop",
"config": {
"items": "{{steps.calculate-health-scores.output}}",
"step": {
"type": "action",
"config": {
"connector": "hubspot",
"action": "updateContact",
"contactId": "{{item.contactId}}",
"properties": {
"health_score": "{{item.healthScore}}",
"health_score_updated": "{{now | date: '%Y-%m-%d'}}"
}
}
}
}
},
{
"id": "find-at-risk",
"type": "transform",
"config": {
"operation": "filter",
"data": "{{steps.calculate-health-scores.output}}",
"condition": "{{item.healthScore < 50}}"
}
},
{
"id": "alert-at-risk",
"type": "condition",
"config": {
"if": "{{steps.find-at-risk.output.length > 0}}",
"then": "notify-at-risk",
"else": "end"
}
},
{
"id": "notify-at-risk",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "#cs-alerts",
"blocks": [
{
"type": "header",
"text": { "type": "plain_text", "text": "At-Risk Customers Alert" }
},
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "{{steps.find-at-risk.output.length}} customers have health scores below 50:\n\n{{#each steps.find-at-risk.output}}• {{this.email}} (Score: {{this.healthScore}})\n{{/each}}"
}
}
]
}
}
]
}
```
**Benefits:**
- Health scores updated consistently
- At-risk accounts identified automatically
- CSM team alerted proactively
- Data-driven customer management
---
### Renewal Management
**Trigger:** 90 days before subscription renewal
**Actions:** Create renewal opportunity, notify CSM, send customer email
Proactively manage renewals before they become urgent.
```json
{
"name": "Renewal Management",
"trigger": {
"type": "schedule",
"cron": "0 8 * * 1"
},
"steps": [
{
"id": "find-upcoming-renewals",
"type": "action",
"config": {
"connector": "stripe",
"action": "listSubscriptions",
"status": "active",
"current_period_end": {
"$gte": "{{now | dateAdd: 60, 'days' | date: '%s'}}",
"$lte": "{{now | dateAdd: 90, 'days' | date: '%s'}}"
}
}
},
{
"id": "process-renewals",
"type": "loop",
"config": {
"items": "{{steps.find-upcoming-renewals.output.data}}",
"step": {
"type": "action",
"config": {
"connector": "hubspot",
"action": "createDeal",
"properties": {
"dealname": "{{item.customer.name}} - Renewal",
"dealstage": "renewal_upcoming",
"amount": "{{item.items.data.[0].price.unit_amount | divided_by: 100 | multiply: 12}}",
"closedate": "{{item.current_period_end | date: '%Y-%m-%d'}}",
"deal_type": "renewal",
"stripe_subscription_id": "{{item.id}}"
}
}
}
}
},
{
"id": "notify-csms",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "#cs-renewals",
"blocks": [
{
"type": "header",
"text": { "type": "plain_text", "text": "Upcoming Renewals (60-90 days)" }
},
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "{{steps.find-upcoming-renewals.output.data.length}} renewals coming up:\n\n{{#each steps.find-upcoming-renewals.output.data}}• {{this.customer.name}} - ${{this.items.data.[0].price.unit_amount | divided_by: 100}}/mo - Renews {{this.current_period_end | date: '%B %d'}}\n{{/each}}"
}
}
]
}
}
]
}
```
---
### Churn Prevention
**Trigger:** Health score drops below threshold
**Actions:** Create urgent task, notify manager, send check-in email
Automatically intervene when customer health declines.
```json
{
"name": "Churn Prevention",
"trigger": {
"type": "webhook",
"provider": "hubspot",
"events": ["contact.propertyChange"],
"filter": {
"propertyName": { "$eq": "health_score" }
}
},
"steps": [
{
"id": "get-contact",
"type": "action",
"config": {
"connector": "hubspot",
"action": "getContact",
"contactId": "{{input.objectId}}"
}
},
{
"id": "check-threshold",
"type": "condition",
"config": {
"if": "{{steps.get-contact.output.properties.health_score < 40}}",
"then": "trigger-intervention",
"else": "end"
}
},
{
"id": "trigger-intervention",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "#cs-urgent",
"blocks": [
{
"type": "header",
"text": { "type": "plain_text", "text": "Churn Risk Alert" }
},
{
"type": "section",
"fields": [
{ "type": "mrkdwn", "text": "*Customer:*\n{{steps.get-contact.output.properties.firstname}} {{steps.get-contact.output.properties.lastname}}" },
{ "type": "mrkdwn", "text": "*Company:*\n{{steps.get-contact.output.properties.company}}" },
{ "type": "mrkdwn", "text": "*Health Score:*\n{{steps.get-contact.output.properties.health_score}}" },
{ "type": "mrkdwn", "text": "*MRR:*\n${{steps.get-contact.output.properties.mrr}}" }
]
},
{
"type": "context",
"elements": [
{ "type": "mrkdwn", "text": "Last login: {{steps.get-contact.output.properties.last_login_date}} | Open tickets: {{steps.get-contact.output.properties.open_tickets}}" }
]
},
{
"type": "actions",
"elements": [
{
"type": "button",
"text": { "type": "plain_text", "text": "View Customer" },
"style": "primary",
"url": "https://app.hubspot.com/contacts/PORTAL/contact/{{input.objectId}}"
},
{
"type": "button",
"text": { "type": "plain_text", "text": "Schedule Call" },
"url": "https://meetings.hubspot.com/csm-calendar"
}
]
}
]
}
},
{
"id": "send-checkin-email",
"type": "email",
"config": {
"action": "send",
"provider": "gmail",
"to": "{{steps.get-contact.output.properties.email}}",
"from": "success@company.com",
"subject": "How can we help?",
"body": {
"html": "Hi {{steps.get-contact.output.properties.firstname}},
I noticed it's been a while since we connected. I wanted to check in and see how things are going with Company.
Are there any challenges I can help with? I'd love to schedule a quick call to make sure you're getting the most out of your subscription.
Book a time that works for you
Looking forward to connecting!
"
}
}
},
{
"id": "update-status",
"type": "action",
"config": {
"connector": "hubspot",
"action": "updateContact",
"contactId": "{{input.objectId}}",
"properties": {
"customer_status": "At Risk",
"churn_intervention_date": "{{now | date: '%Y-%m-%d'}}"
}
}
}
]
}
```
**Benefits:**
- Immediate intervention on health drops
- CS team notified with context
- Automated customer outreach
- Full tracking of intervention
---
### NPS Survey Automation
**Trigger:** 30 days after subscription start
**Actions:** Send NPS survey, collect response, update customer record
Automatically collect NPS feedback at the right time.
```json
{
"name": "NPS Survey",
"trigger": {
"type": "schedule",
"cron": "0 10 * * *"
},
"steps": [
{
"id": "find-eligible-customers",
"type": "action",
"config": {
"connector": "hubspot",
"action": "searchContacts",
"filter": {
"lifecyclestage": { "$eq": "customer" },
"subscription_start_date": {
"$gte": "{{now | dateAdd: -31, 'days' | date: '%Y-%m-%d'}}",
"$lte": "{{now | dateAdd: -29, 'days' | date: '%Y-%m-%d'}}"
},
"nps_sent_date": { "$not_exists": true }
}
}
},
{
"id": "send-nps-surveys",
"type": "loop",
"config": {
"items": "{{steps.find-eligible-customers.output.results}}",
"step": {
"type": "email",
"config": {
"action": "send",
"provider": "resend",
"to": "{{item.properties.email}}",
"from": "feedback@company.com",
"subject": "How likely are you to recommend Company?",
"body": {
"html": "Hi {{item.properties.firstname}},
You've been using Company for about a month now. We'd love your feedback!
How likely are you to recommend Company to a friend or colleague?
10 - Extremely likely | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 - Not at all likely
Thank you for your feedback!
"
}
}
}
}
},
{
"id": "update-sent-dates",
"type": "loop",
"config": {
"items": "{{steps.find-eligible-customers.output.results}}",
"step": {
"type": "action",
"config": {
"connector": "hubspot",
"action": "updateContact",
"contactId": "{{item.id}}",
"properties": {
"nps_sent_date": "{{now | date: '%Y-%m-%d'}}"
}
}
}
}
},
{
"id": "notify-cs",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "#cs-feedback",
"text": "NPS surveys sent to {{steps.find-eligible-customers.output.results.length}} customers today."
}
}
]
}
```
---
### Expansion Opportunity Detection
**Trigger:** Usage exceeds plan limits
**Actions:** Create upsell opportunity, notify AE, send upgrade email
Automatically identify and act on expansion opportunities.
```json
{
"name": "Expansion Opportunity",
"trigger": {
"type": "webhook",
"provider": "custom",
"events": ["usage.threshold_exceeded"]
},
"steps": [
{
"id": "get-customer",
"type": "action",
"config": {
"connector": "hubspot",
"action": "getContact",
"email": "{{input.customer_email}}"
}
},
{
"id": "create-upsell-deal",
"type": "action",
"config": {
"connector": "hubspot",
"action": "createDeal",
"properties": {
"dealname": "{{steps.get-customer.output.properties.company}} - Upgrade",
"dealstage": "expansion_identified",
"deal_type": "expansion",
"amount": "{{input.upgrade_value}}",
"notes": "Customer exceeded {{input.metric_name}}: {{input.current_usage}} / {{input.limit}}"
},
"associations": [{
"to": "{{steps.get-customer.output.id}}",
"type": "contact"
}]
}
},
{
"id": "notify-ae",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "#expansion-opps",
"blocks": [
{
"type": "header",
"text": { "type": "plain_text", "text": "Expansion Opportunity" }
},
{
"type": "section",
"fields": [
{ "type": "mrkdwn", "text": "*Customer:*\n{{steps.get-customer.output.properties.company}}" },
{ "type": "mrkdwn", "text": "*Current Plan:*\n{{steps.get-customer.output.properties.subscription_plan}}" },
{ "type": "mrkdwn", "text": "*Metric:*\n{{input.metric_name}}" },
{ "type": "mrkdwn", "text": "*Usage:*\n{{input.current_usage}} / {{input.limit}} ({{input.usage_pct}}%)" }
]
},
{
"type": "actions",
"elements": [
{
"type": "button",
"text": { "type": "plain_text", "text": "View Deal" },
"style": "primary",
"url": "https://app.hubspot.com/contacts/PORTAL/deal/{{steps.create-upsell-deal.output.id}}"
}
]
}
]
}
},
{
"id": "send-upgrade-email",
"type": "email",
"config": {
"action": "send",
"provider": "gmail",
"to": "{{input.customer_email}}",
"from": "success@company.com",
"subject": "You're outgrowing your plan!",
"body": {
"html": "Hi {{steps.get-customer.output.properties.firstname}},
Great news - you've been getting a lot of value from Company! You're currently using {{input.usage_pct}}% of your {{input.metric_name}} limit.
To ensure uninterrupted service, you might want to consider upgrading to our {{input.recommended_plan}} plan.
View upgrade options
Questions? Reply to this email or book a call with your success manager.
"
}
}
}
]
}
```
## Key Integrations
| Integration | Use Cases |
|-------------|-----------|
| **Stripe** | Subscriptions, billing, customer data |
| **HubSpot** | CRM, contacts, deals, health tracking |
| **Salesforce** | CRM, accounts, opportunities |
| **QuickBooks** | Customer records, invoicing |
| **Slack** | Team notifications, alerts |
| **Email** | Customer communication, surveys |
## Best Practices
### 1. Health Score Components
Build composite health scores from multiple signals:
```json
{
"healthScore": "{{(loginScore * 0.3) + (usageScore * 0.4) + (supportScore * 0.3)}}"
}
```
### 2. Tiered Interventions
Different actions for different severity levels:
```json
{
"id": "route-by-severity",
"type": "condition",
"config": {
"if": "{{healthScore < 30}}",
"then": "urgent-intervention",
"else": {
"if": "{{healthScore < 50}}",
"then": "standard-intervention",
"else": "monitor"
}
}
}
```
### 3. Timing Matters
Send communications at optimal times:
```json
{
"trigger": {
"type": "schedule",
"cron": "0 10 * * 2"
}
}
```
### 4. Track Everything
Always log actions taken:
```json
{
"id": "log-intervention",
"type": "action",
"config": {
"connector": "hubspot",
"action": "updateContact",
"properties": {
"last_intervention_date": "{{now}}",
"intervention_type": "churn_prevention"
}
}
}
```
## Getting Started
1. **[Customer Onboarding Tutorial](/docs/tutorials/customer-onboarding)** - Start with automated onboarding
2. **[Stripe Integration Guide](/docs/integrations/payments/stripe)** - Set up subscription tracking
3. **[HubSpot Integration Guide](/docs/integrations/crm/hubspot)** - Connect your CRM
4. **[Email Block Reference](/docs/workflows/building-blocks/email-block)** - Learn email automation
## Related Resources
- [Invoice Automation Tutorial](/docs/tutorials/invoice-automation)
- [Slack Block Reference](/docs/workflows/building-blocks/slack-block)
- [Finance Team Use Cases](/docs/use-cases/finance-teams)
- [Sales Ops Use Cases](/docs/use-cases/sales-ops)
# Finance Teams (/docs/use-cases/finance-teams)
Workflow patterns for finance and billing automation
## Finance Team Workflows
Automate invoicing, payment reconciliation, revenue recognition, and financial operations across your billing and accounting systems.
## Why Automate Finance Operations?
Finance teams face unique challenges:
- **Manual data entry** across multiple systems (CRM, billing, accounting)
- **Delayed invoicing** waiting for deal information from sales
- **Reconciliation bottlenecks** matching payments to invoices
- **Month-end crunches** racing to close books on time
- **Audit trail gaps** when processes aren't documented
Workflow automation solves these by:
- Eliminating copy-paste between systems
- Triggering actions instantly when events occur
- Maintaining audit trails automatically
- Reducing errors from manual data entry
- Freeing up time for strategic analysis
## Common Workflow Patterns
### Invoice Automation
**Trigger:** CRM deal closes won
**Actions:** Create invoice, send to customer, update CRM
Automatically generate invoices when sales deals close, eliminating the handoff delay between sales and finance.
```json
{
"name": "Deal Close → Invoice",
"trigger": {
"type": "webhook",
"provider": "salesforce",
"events": ["opportunity.updated"],
"filter": {
"StageName": { "$eq": "Closed Won" }
}
},
"steps": [
{
"id": "get-account",
"type": "action",
"config": {
"connector": "salesforce",
"action": "getAccount",
"accountId": "{{input.payload.AccountId}}"
}
},
{
"id": "create-invoice",
"type": "action",
"config": {
"connector": "stripe",
"action": "createInvoice",
"customer": "{{steps.get-account.output.Stripe_Customer_ID__c}}",
"collection_method": "send_invoice",
"days_until_due": 30
}
},
{
"id": "add-line-item",
"type": "action",
"config": {
"connector": "stripe",
"action": "createInvoiceItem",
"customer": "{{steps.get-account.output.Stripe_Customer_ID__c}}",
"invoice": "{{steps.create-invoice.output.id}}",
"description": "{{input.payload.Name}}",
"amount": "{{input.payload.Amount | multiply: 100}}",
"currency": "usd"
}
},
{
"id": "finalize-and-send",
"type": "action",
"config": {
"connector": "stripe",
"action": "sendInvoice",
"invoiceId": "{{steps.create-invoice.output.id}}"
}
},
{
"id": "update-opportunity",
"type": "action",
"config": {
"connector": "salesforce",
"action": "updateOpportunity",
"opportunityId": "{{input.payload.Id}}",
"fields": {
"Invoice_URL__c": "{{steps.finalize-and-send.output.hosted_invoice_url}}",
"Invoice_Status__c": "Sent"
}
}
}
]
}
```
**Benefits:**
- Invoice sent within seconds of deal close
- No manual data entry errors
- Full audit trail in CRM
- Customer receives invoice immediately
[Full Invoice Automation Tutorial →](/docs/tutorials/invoice-automation)
---
### Payment Reconciliation
**Trigger:** Payment received in Stripe
**Actions:** Match to invoice, update accounting, notify team
Automatically reconcile payments when they arrive, updating both accounting and CRM systems.
```json
{
"name": "Payment Reconciliation",
"trigger": {
"type": "webhook",
"provider": "stripe",
"events": ["invoice.payment_succeeded"]
},
"steps": [
{
"id": "get-invoice-details",
"type": "action",
"config": {
"connector": "stripe",
"action": "getInvoice",
"invoiceId": "{{input.data.object.id}}"
}
},
{
"id": "find-qb-invoice",
"type": "action",
"config": {
"connector": "quickbooks",
"action": "query",
"query": "SELECT * FROM Invoice WHERE DocNumber = '{{steps.get-invoice-details.output.number}}'"
}
},
{
"id": "record-payment",
"type": "action",
"config": {
"connector": "quickbooks",
"action": "createPayment",
"CustomerRef": {
"value": "{{steps.find-qb-invoice.output.QueryResponse.Invoice.[0].CustomerRef.value}}"
},
"TotalAmt": "{{input.data.object.amount_paid | divided_by: 100}}",
"Line": [{
"Amount": "{{input.data.object.amount_paid | divided_by: 100}}",
"LinkedTxn": [{
"TxnId": "{{steps.find-qb-invoice.output.QueryResponse.Invoice.[0].Id}}",
"TxnType": "Invoice"
}]
}]
}
},
{
"id": "update-crm",
"type": "action",
"config": {
"connector": "salesforce",
"action": "query",
"query": "UPDATE Opportunity SET Invoice_Status__c = 'Paid' WHERE Stripe_Invoice_ID__c = '{{input.data.object.id}}'"
}
},
{
"id": "notify-finance",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "#finance-payments",
"text": "Payment received: ${{input.data.object.amount_paid | divided_by: 100}} from {{steps.get-invoice-details.output.customer_name}} for invoice #{{steps.get-invoice-details.output.number}}"
}
}
]
}
```
**Benefits:**
- Real-time payment tracking
- Automatic QuickBooks reconciliation
- CRM status always current
- Finance team notified instantly
---
### Revenue Recognition
**Trigger:** Scheduled monthly (1st of month)
**Actions:** Query subscriptions, calculate MRR/ARR, update spreadsheet
Automate monthly revenue calculations for accurate financial reporting.
```json
{
"name": "Monthly Revenue Recognition",
"trigger": {
"type": "schedule",
"cron": "0 6 1 * *"
},
"steps": [
{
"id": "get-active-subscriptions",
"type": "action",
"config": {
"connector": "stripe",
"action": "listSubscriptions",
"status": "active"
}
},
{
"id": "calculate-metrics",
"type": "transform",
"config": {
"operation": "reduce",
"data": "{{steps.get-active-subscriptions.output.data}}",
"accumulator": {
"mrr": 0,
"customer_count": 0
},
"expression": {
"mrr": "{{acc.mrr + (item.items.data.[0].price.unit_amount / 100)}}",
"customer_count": "{{acc.customer_count + 1}}"
}
}
},
{
"id": "create-journal-entry",
"type": "action",
"config": {
"connector": "netsuite",
"action": "createJournalEntry",
"subsidiary": { "id": "1" },
"trandate": "{{now | date: '%Y-%m-01'}}",
"memo": "Monthly Revenue Recognition - {{now | date: '%B %Y'}}",
"line": [
{
"account": { "id": "123" },
"debit": "{{steps.calculate-metrics.output.mrr}}"
},
{
"account": { "id": "456" },
"credit": "{{steps.calculate-metrics.output.mrr}}"
}
]
}
},
{
"id": "notify-finance",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "#finance-metrics",
"blocks": [
{
"type": "header",
"text": { "type": "plain_text", "text": "Monthly Revenue Report" }
},
{
"type": "section",
"fields": [
{ "type": "mrkdwn", "text": "*MRR:* ${{steps.calculate-metrics.output.mrr | number_format: 2}}" },
{ "type": "mrkdwn", "text": "*ARR:* ${{steps.calculate-metrics.output.mrr | multiply: 12 | number_format: 2}}" },
{ "type": "mrkdwn", "text": "*Active Customers:* {{steps.calculate-metrics.output.customer_count}}" }
]
}
]
}
}
]
}
```
**Benefits:**
- Consistent monthly calculations
- Automatic journal entries
- Team visibility into metrics
- Reduces month-end workload
---
### Dunning Automation
**Trigger:** Invoice overdue
**Actions:** Send reminder emails, update customer status, notify sales
Automatically follow up on overdue invoices without manual tracking.
```json
{
"name": "Invoice Dunning",
"trigger": {
"type": "webhook",
"provider": "stripe",
"events": ["invoice.payment_failed"]
},
"steps": [
{
"id": "get-customer",
"type": "action",
"config": {
"connector": "stripe",
"action": "getCustomer",
"customerId": "{{input.data.object.customer}}"
}
},
{
"id": "send-reminder-email",
"type": "email",
"config": {
"action": "send",
"provider": "resend",
"to": "{{steps.get-customer.output.email}}",
"from": "billing@company.com",
"subject": "Payment Failed - Action Required",
"body": {
"html": "Hi {{steps.get-customer.output.name}},
We were unable to process your payment of ${{input.data.object.amount_due | divided_by: 100}} for invoice #{{input.data.object.number}}.
Please update your payment method to avoid service interruption.
Update Payment Method
"
}
}
},
{
"id": "update-hubspot-status",
"type": "action",
"config": {
"connector": "hubspot",
"action": "updateContact",
"email": "{{steps.get-customer.output.email}}",
"properties": {
"payment_status": "Failed",
"last_payment_attempt": "{{now | date: '%Y-%m-%d'}}"
}
}
},
{
"id": "notify-account-owner",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "#sales-alerts",
"text": ":warning: Payment failed for {{steps.get-customer.output.name}}. Invoice #{{input.data.object.number}} for ${{input.data.object.amount_due | divided_by: 100}}. <{{input.data.object.hosted_invoice_url}}|View Invoice>"
}
}
]
}
```
**Benefits:**
- Immediate customer notification
- Sales visibility into at-risk accounts
- Consistent follow-up process
- Reduced churn from payment issues
---
### Subscription Billing Sync
**Trigger:** Subscription changes in Stripe
**Actions:** Update accounting records, sync to ERP
Keep billing and accounting systems in sync when subscriptions change.
```json
{
"name": "Subscription → Accounting Sync",
"trigger": {
"type": "webhook",
"provider": "stripe",
"events": ["customer.subscription.updated", "customer.subscription.deleted"]
},
"steps": [
{
"id": "get-subscription",
"type": "action",
"config": {
"connector": "stripe",
"action": "getSubscription",
"subscriptionId": "{{input.data.object.id}}"
}
},
{
"id": "find-netsuite-customer",
"type": "action",
"config": {
"connector": "netsuite",
"action": "searchRecords",
"query": "SELECT id FROM customer WHERE custentity_stripe_id = '{{input.data.object.customer}}'"
}
},
{
"id": "update-subscription-record",
"type": "action",
"config": {
"connector": "netsuite",
"action": "updateRecord",
"type": "customrecord_subscription",
"id": "{{steps.find-netsuite-customer.output.id}}",
"values": {
"custrecord_sub_status": "{{input.data.object.status}}",
"custrecord_sub_mrr": "{{steps.get-subscription.output.items.data.[0].price.unit_amount | divided_by: 100}}",
"custrecord_sub_next_billing": "{{input.data.object.current_period_end | date: '%Y-%m-%d'}}"
}
}
}
]
}
```
---
### Expense Approval Workflow
**Trigger:** Expense submitted via API
**Actions:** Route for approval, notify manager, process payment
Automate expense approval workflows with Slack integration.
```json
{
"name": "Expense Approval",
"trigger": {
"type": "api"
},
"steps": [
{
"id": "determine-approver",
"type": "transform",
"config": {
"operation": "map",
"data": {
"approver": "{{#if (gt input.amount 1000)}}cfo@company.com{{else}}manager@company.com{{/if}}",
"approverSlackId": "{{#if (gt input.amount 1000)}}U_CFO{{else}}U_MANAGER{{/if}}"
}
}
},
{
"id": "request-approval",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "#expense-approvals",
"blocks": [
{
"type": "header",
"text": { "type": "plain_text", "text": "Expense Approval Request" }
},
{
"type": "section",
"fields": [
{ "type": "mrkdwn", "text": "*Submitted By:* {{input.employee_name}}" },
{ "type": "mrkdwn", "text": "*Amount:* ${{input.amount}}" },
{ "type": "mrkdwn", "text": "*Category:* {{input.category}}" },
{ "type": "mrkdwn", "text": "*Description:* {{input.description}}" }
]
},
{
"type": "actions",
"elements": [
{
"type": "button",
"text": { "type": "plain_text", "text": "Approve" },
"style": "primary",
"action_id": "approve_expense_{{input.expense_id}}"
},
{
"type": "button",
"text": { "type": "plain_text", "text": "Reject" },
"style": "danger",
"action_id": "reject_expense_{{input.expense_id}}"
}
]
}
]
}
}
]
}
```
## Key Integrations
| Integration | Use Cases |
|-------------|-----------|
| **Stripe** | Invoicing, payments, subscriptions, customer management |
| **QuickBooks** | Accounting records, payments, journal entries |
| **NetSuite** | ERP integration, revenue recognition, multi-entity |
| **Salesforce** | CRM updates, opportunity tracking, customer data |
| **HubSpot** | Customer status, lifecycle tracking |
| **Slack** | Notifications, approvals, alerts |
| **Email** | Customer invoices, payment reminders |
## Best Practices
### 1. Idempotency
Always include unique identifiers to prevent duplicate processing:
```json
{
"metadata": {
"salesforce_opportunity_id": "{{input.payload.Id}}",
"processed_at": "{{now}}"
}
}
```
### 2. Error Handling
Use graceful degradation for non-critical steps:
```json
{
"onError": {
"action": "continue",
"fallback": { "id": null }
}
}
```
### 3. Audit Trails
Always update source systems with results:
```json
{
"id": "update-source",
"type": "action",
"config": {
"connector": "salesforce",
"action": "updateOpportunity",
"fields": {
"Invoice_Created_At__c": "{{now}}",
"Invoice_ID__c": "{{steps.create-invoice.output.id}}"
}
}
}
```
### 4. Amount Handling
Remember Stripe amounts are in cents:
```json
{
"amount": "{{input.Amount | multiply: 100}}",
"display_amount": "{{input.data.object.amount | divided_by: 100}}"
}
```
## Getting Started
1. **[Invoice Automation Tutorial](/docs/tutorials/invoice-automation)** - Start with deal-to-invoice automation
2. **[Stripe Integration Guide](/docs/integrations/payments/stripe)** - Set up your Stripe connection
3. **[QuickBooks Integration Guide](/docs/integrations/accounting/quickbooks)** - Connect your accounting system
4. **[Transform Steps](/docs/workflows/steps/transforms)** - Learn data transformation patterns
## Related Resources
- [Customer Onboarding Tutorial](/docs/tutorials/customer-onboarding)
- [Email Block Reference](/docs/workflows/building-blocks/email-block)
- [Slack Block Reference](/docs/workflows/building-blocks/slack-block)
- [NetSuite Integration Guide](/docs/integrations/accounting/netsuite)
# Sales Operations (/docs/use-cases/sales-ops)
Workflow patterns for sales teams and revenue operations
## Sales Operations Workflows
Automate deal progression, contract generation, lead routing, and pipeline management across your CRM and sales tools.
## Why Automate Sales Operations?
Sales ops teams face unique challenges:
- **Manual handoffs** between sales stages slow deal velocity
- **Contract delays** while waiting for legal and document preparation
- **Lead routing inefficiencies** causing uneven rep workloads
- **CRM data decay** as reps forget to update records
- **Pipeline visibility gaps** requiring manual report generation
Workflow automation solves these by:
- Automating stage transitions and handoffs
- Generating contracts instantly when deals are ready
- Routing leads based on rules and rep capacity
- Keeping CRM data current automatically
- Providing real-time pipeline visibility
## Common Workflow Patterns
### Deal-to-Contract Automation
**Trigger:** Deal reaches contract stage
**Actions:** Create contract from template, send for signature
Automatically generate and send contracts when deals reach the right stage, eliminating manual document creation.
```json
{
"name": "Deal → Contract",
"trigger": {
"type": "webhook",
"provider": "hubspot",
"events": ["deal.propertyChange"],
"filter": {
"propertyName": { "$eq": "dealstage" },
"propertyValue": { "$eq": "contractsent" }
}
},
"steps": [
{
"id": "get-deal",
"type": "action",
"config": {
"connector": "hubspot",
"action": "getDeal",
"dealId": "{{input.objectId}}",
"associations": ["contacts", "companies"]
}
},
{
"id": "get-contact",
"type": "action",
"config": {
"connector": "hubspot",
"action": "getContact",
"contactId": "{{steps.get-deal.output.associations.contacts.results.[0].id}}"
}
},
{
"id": "get-company",
"type": "action",
"config": {
"connector": "hubspot",
"action": "getCompany",
"companyId": "{{steps.get-deal.output.associations.companies.results.[0].id}}"
}
},
{
"id": "create-contract",
"type": "action",
"config": {
"connector": "pandadoc",
"action": "createDocument",
"templateId": "CONTRACT_TEMPLATE_ID",
"name": "Contract - {{steps.get-deal.output.properties.dealname}}",
"recipients": [{
"email": "{{steps.get-contact.output.properties.email}}",
"first_name": "{{steps.get-contact.output.properties.firstname}}",
"last_name": "{{steps.get-contact.output.properties.lastname}}",
"role": "Signer"
}],
"tokens": [
{ "name": "deal_name", "value": "{{steps.get-deal.output.properties.dealname}}" },
{ "name": "deal_amount", "value": "{{steps.get-deal.output.properties.amount}}" },
{ "name": "company_name", "value": "{{steps.get-company.output.properties.name}}" }
]
}
},
{
"id": "send-contract",
"type": "action",
"config": {
"connector": "pandadoc",
"action": "sendDocument",
"documentId": "{{steps.create-contract.output.id}}",
"message": "Please review and sign your contract."
}
},
{
"id": "update-deal",
"type": "action",
"config": {
"connector": "hubspot",
"action": "updateDeal",
"dealId": "{{input.objectId}}",
"properties": {
"contract_url": "https://app.pandadoc.com/documents/{{steps.create-contract.output.id}}",
"contract_status": "Sent"
}
}
},
{
"id": "notify-sales",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "#sales-contracts",
"text": "Contract sent for {{steps.get-deal.output.properties.dealname}} (${{steps.get-deal.output.properties.amount}}) to {{steps.get-contact.output.properties.email}}"
}
}
]
}
```
**Benefits:**
- Contract sent within seconds of stage change
- No manual document assembly
- Deal always has contract link for tracking
- Team visibility into contract status
[Full Deal Sync Tutorial →](/docs/tutorials/deal-sync)
---
### Quote Generation
**Trigger:** API call from CRM or form
**Actions:** Calculate pricing, generate PDF, attach to deal
Automatically generate quotes with correct pricing and terms.
```json
{
"name": "Generate Quote",
"trigger": {
"type": "api"
},
"steps": [
{
"id": "get-pricing",
"type": "action",
"config": {
"connector": "stripe",
"action": "getPrice",
"priceId": "{{input.price_id}}"
}
},
{
"id": "calculate-quote",
"type": "transform",
"config": {
"operation": "map",
"data": {
"unit_price": "{{steps.get-pricing.output.unit_amount | divided_by: 100}}",
"quantity": "{{input.quantity}}",
"subtotal": "{{steps.get-pricing.output.unit_amount | divided_by: 100 | multiply: input.quantity}}",
"discount": "{{#if (gt input.quantity 10)}}{{steps.get-pricing.output.unit_amount | divided_by: 100 | multiply: input.quantity | multiply: 0.1}}{{else}}0{{/if}}",
"total": "{{#if (gt input.quantity 10)}}{{steps.get-pricing.output.unit_amount | divided_by: 100 | multiply: input.quantity | multiply: 0.9}}{{else}}{{steps.get-pricing.output.unit_amount | divided_by: 100 | multiply: input.quantity}}{{/if}}"
}
}
},
{
"id": "create-quote-doc",
"type": "action",
"config": {
"connector": "pandadoc",
"action": "createDocument",
"templateId": "QUOTE_TEMPLATE_ID",
"name": "Quote - {{input.company_name}} - {{now | date: '%Y-%m-%d'}}",
"recipients": [{
"email": "{{input.contact_email}}",
"first_name": "{{input.contact_first_name}}",
"last_name": "{{input.contact_last_name}}"
}],
"tokens": [
{ "name": "company_name", "value": "{{input.company_name}}" },
{ "name": "product_name", "value": "{{steps.get-pricing.output.product.name}}" },
{ "name": "unit_price", "value": "{{steps.calculate-quote.output.unit_price}}" },
{ "name": "quantity", "value": "{{input.quantity}}" },
{ "name": "discount", "value": "{{steps.calculate-quote.output.discount}}" },
{ "name": "total", "value": "{{steps.calculate-quote.output.total}}" },
{ "name": "valid_until", "value": "{{now | dateAdd: 30, 'days' | date: '%B %d, %Y'}}" }
]
}
},
{
"id": "update-deal",
"type": "action",
"config": {
"connector": "hubspot",
"action": "updateDeal",
"dealId": "{{input.deal_id}}",
"properties": {
"quote_url": "https://app.pandadoc.com/documents/{{steps.create-quote-doc.output.id}}",
"amount": "{{steps.calculate-quote.output.total}}"
}
}
}
]
}
```
**Benefits:**
- Accurate pricing every time
- Volume discounts applied automatically
- Quote linked to CRM deal
- Consistent professional documents
---
### Lead Routing
**Trigger:** New lead created in CRM
**Actions:** Enrich data, score lead, assign to rep, notify
Automatically route leads to the right sales rep based on territory, product interest, or round-robin.
```json
{
"name": "Lead Router",
"trigger": {
"type": "webhook",
"provider": "hubspot",
"events": ["contact.creation"]
},
"steps": [
{
"id": "get-contact",
"type": "action",
"config": {
"connector": "hubspot",
"action": "getContact",
"contactId": "{{input.objectId}}",
"properties": ["email", "company", "country", "jobtitle", "hs_lead_status"]
}
},
{
"id": "determine-territory",
"type": "transform",
"config": {
"operation": "map",
"data": {
"region": "{{#if (or (eq steps.get-contact.output.properties.country 'United States') (eq steps.get-contact.output.properties.country 'Canada'))}}NA{{else if (or (eq steps.get-contact.output.properties.country 'United Kingdom') (eq steps.get-contact.output.properties.country 'Germany'))}}EMEA{{else}}APAC{{/if}}"
}
}
},
{
"id": "calculate-lead-score",
"type": "transform",
"config": {
"operation": "map",
"data": {
"score": "{{0 | plus: (if (contains steps.get-contact.output.properties.jobtitle 'VP') 30 else 0) | plus: (if (contains steps.get-contact.output.properties.jobtitle 'Director') 20 else 0) | plus: (if (contains steps.get-contact.output.properties.jobtitle 'Manager') 10 else 0) | plus: (if steps.get-contact.output.properties.company 15 else 0)}}"
}
}
},
{
"id": "assign-owner",
"type": "transform",
"config": {
"operation": "map",
"data": {
"ownerId": "{{#if (and (eq steps.determine-territory.output.region 'NA') (gt steps.calculate-lead-score.output.score 40))}}NA_ENTERPRISE_REP_ID{{else if (eq steps.determine-territory.output.region 'NA')}}NA_SMB_REP_ID{{else if (eq steps.determine-territory.output.region 'EMEA')}}EMEA_REP_ID{{else}}APAC_REP_ID{{/if}}",
"ownerEmail": "{{#if (eq steps.determine-territory.output.region 'NA')}}sales-na@company.com{{else if (eq steps.determine-territory.output.region 'EMEA')}}sales-emea@company.com{{else}}sales-apac@company.com{{/if}}"
}
}
},
{
"id": "update-contact-owner",
"type": "action",
"config": {
"connector": "hubspot",
"action": "updateContact",
"contactId": "{{input.objectId}}",
"properties": {
"hubspot_owner_id": "{{steps.assign-owner.output.ownerId}}",
"hs_lead_status": "NEW",
"lead_score": "{{steps.calculate-lead-score.output.score}}",
"sales_region": "{{steps.determine-territory.output.region}}"
}
}
},
{
"id": "notify-rep",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "#sales-leads",
"blocks": [
{
"type": "header",
"text": { "type": "plain_text", "text": "New Lead Assigned" }
},
{
"type": "section",
"fields": [
{ "type": "mrkdwn", "text": "*Name:*\n{{steps.get-contact.output.properties.firstname}} {{steps.get-contact.output.properties.lastname}}" },
{ "type": "mrkdwn", "text": "*Company:*\n{{steps.get-contact.output.properties.company}}" },
{ "type": "mrkdwn", "text": "*Title:*\n{{steps.get-contact.output.properties.jobtitle}}" },
{ "type": "mrkdwn", "text": "*Score:*\n{{steps.calculate-lead-score.output.score}}" }
]
},
{
"type": "context",
"elements": [
{ "type": "mrkdwn", "text": "Region: {{steps.determine-territory.output.region}} | Assigned to: {{steps.assign-owner.output.ownerEmail}}" }
]
},
{
"type": "actions",
"elements": [
{
"type": "button",
"text": { "type": "plain_text", "text": "View in HubSpot" },
"url": "https://app.hubspot.com/contacts/YOUR_PORTAL/contact/{{input.objectId}}"
}
]
}
]
}
}
]
}
```
**Benefits:**
- Instant lead assignment
- Consistent territory rules
- Lead scoring automation
- Rep notification with context
---
### Pipeline Sync
**Trigger:** Scheduled hourly
**Actions:** Sync deals between CRM and other systems
Keep multiple systems in sync with scheduled pipeline synchronization.
```json
{
"name": "Pipeline Sync",
"trigger": {
"type": "schedule",
"cron": "0 * * * *"
},
"steps": [
{
"id": "get-updated-deals",
"type": "action",
"config": {
"connector": "hubspot",
"action": "searchDeals",
"filter": {
"lastModifiedDate": { "$gte": "{{now | dateAdd: -1, 'hours'}}" }
}
}
},
{
"id": "sync-to-salesforce",
"type": "loop",
"config": {
"items": "{{steps.get-updated-deals.output.results}}",
"step": {
"type": "action",
"config": {
"connector": "salesforce",
"action": "updateOpportunity",
"opportunityId": "{{item.properties.salesforce_opportunity_id}}",
"fields": {
"Amount": "{{item.properties.amount}}",
"StageName": "{{item.properties.dealstage}}",
"CloseDate": "{{item.properties.closedate}}"
}
}
}
}
},
{
"id": "log-sync",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "#sales-ops",
"text": "Pipeline sync complete. {{steps.get-updated-deals.output.results.length}} deals synced."
}
}
]
}
```
---
### Win/Loss Analysis
**Trigger:** Deal closed (won or lost)
**Actions:** Collect feedback, update analytics, notify team
Automatically capture win/loss data for analysis and reporting.
```json
{
"name": "Win/Loss Capture",
"trigger": {
"type": "webhook",
"provider": "salesforce",
"events": ["opportunity.updated"],
"filter": {
"IsClosed": { "$eq": true }
}
},
"steps": [
{
"id": "get-opportunity",
"type": "action",
"config": {
"connector": "salesforce",
"action": "getOpportunity",
"opportunityId": "{{input.payload.Id}}"
}
},
{
"id": "get-owner",
"type": "action",
"config": {
"connector": "salesforce",
"action": "query",
"query": "SELECT Id, Name, Email FROM User WHERE Id = '{{steps.get-opportunity.output.OwnerId}}'"
}
},
{
"id": "request-feedback",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "@{{steps.get-owner.output.records.[0].Email}}",
"blocks": [
{
"type": "header",
"text": { "type": "plain_text", "text": "{{#if steps.get-opportunity.output.IsWon}}Deal Won!{{else}}Deal Lost{{/if}}" }
},
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "*{{steps.get-opportunity.output.Name}}*\nAmount: ${{steps.get-opportunity.output.Amount}}"
}
},
{
"type": "input",
"block_id": "win_loss_reason",
"label": { "type": "plain_text", "text": "{{#if steps.get-opportunity.output.IsWon}}What was the key factor in winning?{{else}}What was the primary reason for loss?{{/if}}" },
"element": {
"type": "static_select",
"action_id": "reason_select",
"options": [
{ "text": { "type": "plain_text", "text": "Price/Budget" }, "value": "price" },
{ "text": { "type": "plain_text", "text": "Product Fit" }, "value": "product" },
{ "text": { "type": "plain_text", "text": "Competitor" }, "value": "competitor" },
{ "text": { "type": "plain_text", "text": "Timing" }, "value": "timing" },
{ "text": { "type": "plain_text", "text": "Relationship" }, "value": "relationship" }
]
}
}
]
}
},
{
"id": "notify-leadership",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "#sales-wins-losses",
"blocks": [
{
"type": "header",
"text": { "type": "plain_text", "text": "{{#if steps.get-opportunity.output.IsWon}}Won{{else}}Lost{{/if}}: {{steps.get-opportunity.output.Name}}" }
},
{
"type": "section",
"fields": [
{ "type": "mrkdwn", "text": "*Amount:*\n${{steps.get-opportunity.output.Amount}}" },
{ "type": "mrkdwn", "text": "*Owner:*\n{{steps.get-owner.output.records.[0].Name}}" },
{ "type": "mrkdwn", "text": "*Stage:*\n{{steps.get-opportunity.output.StageName}}" },
{ "type": "mrkdwn", "text": "*Type:*\n{{steps.get-opportunity.output.Type}}" }
]
}
]
}
}
]
}
```
---
### Account Executive Handoff
**Trigger:** Lead qualified (MQL → SQL)
**Actions:** Create opportunity, assign AE, schedule meeting
Automate the handoff from SDR to Account Executive.
```json
{
"name": "SDR → AE Handoff",
"trigger": {
"type": "webhook",
"provider": "hubspot",
"events": ["contact.propertyChange"],
"filter": {
"propertyName": { "$eq": "lifecyclestage" },
"propertyValue": { "$eq": "salesqualifiedlead" }
}
},
"steps": [
{
"id": "get-contact",
"type": "action",
"config": {
"connector": "hubspot",
"action": "getContact",
"contactId": "{{input.objectId}}",
"associations": ["companies"]
}
},
{
"id": "determine-ae",
"type": "transform",
"config": {
"operation": "map",
"data": {
"aeId": "AE_OWNER_ID",
"aeEmail": "ae@company.com",
"aeSlackId": "U_AE_SLACK_ID"
}
}
},
{
"id": "create-deal",
"type": "action",
"config": {
"connector": "hubspot",
"action": "createDeal",
"properties": {
"dealname": "{{steps.get-contact.output.properties.company}} - New Opportunity",
"dealstage": "qualifiedtobuy",
"hubspot_owner_id": "{{steps.determine-ae.output.aeId}}",
"pipeline": "default"
},
"associations": [{
"to": "{{input.objectId}}",
"type": "contact"
}]
}
},
{
"id": "notify-ae",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "@{{steps.determine-ae.output.aeSlackId}}",
"blocks": [
{
"type": "header",
"text": { "type": "plain_text", "text": "New SQL Handoff" }
},
{
"type": "section",
"fields": [
{ "type": "mrkdwn", "text": "*Contact:*\n{{steps.get-contact.output.properties.firstname}} {{steps.get-contact.output.properties.lastname}}" },
{ "type": "mrkdwn", "text": "*Company:*\n{{steps.get-contact.output.properties.company}}" },
{ "type": "mrkdwn", "text": "*Title:*\n{{steps.get-contact.output.properties.jobtitle}}" },
{ "type": "mrkdwn", "text": "*Email:*\n{{steps.get-contact.output.properties.email}}" }
]
},
{
"type": "actions",
"elements": [
{
"type": "button",
"text": { "type": "plain_text", "text": "View Deal" },
"url": "https://app.hubspot.com/contacts/YOUR_PORTAL/deal/{{steps.create-deal.output.id}}"
},
{
"type": "button",
"text": { "type": "plain_text", "text": "Schedule Meeting" },
"url": "https://meetings.hubspot.com/ae-calendar"
}
]
}
]
}
},
{
"id": "send-intro-email",
"type": "email",
"config": {
"action": "send",
"provider": "gmail",
"to": "{{steps.get-contact.output.properties.email}}",
"from": "{{steps.determine-ae.output.aeEmail}}",
"subject": "Let's schedule a call - {{steps.get-contact.output.properties.company}}",
"body": {
"html": "Hi {{steps.get-contact.output.properties.firstname}},
I'm your dedicated account executive at Company. I'd love to learn more about your needs and show you how we can help.
Would you have 30 minutes this week for a quick call?
Schedule a time that works for you
"
}
}
}
]
}
```
## Key Integrations
| Integration | Use Cases |
|-------------|-----------|
| **Salesforce** | CRM, opportunities, accounts, contacts |
| **HubSpot** | CRM, deals, contacts, companies |
| **PandaDoc** | Contracts, quotes, proposals |
| **Slack** | Notifications, approvals, team alerts |
| **Stripe** | Pricing, quotes, subscriptions |
| **Email** | Outreach, follow-ups, introductions |
## Best Practices
### 1. Stage-Based Triggers
Use property change events instead of polling:
```json
{
"trigger": {
"type": "webhook",
"provider": "hubspot",
"events": ["deal.propertyChange"],
"filter": {
"propertyName": { "$eq": "dealstage" }
}
}
}
```
### 2. Owner Notifications
Always notify the record owner:
```json
{
"id": "notify-owner",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "@{{steps.get-owner.output.slack_id}}"
}
}
```
### 3. Link Back to CRM
Include CRM links in all notifications:
```json
{
"type": "button",
"text": { "type": "plain_text", "text": "View in CRM" },
"url": "https://app.hubspot.com/contacts/PORTAL/deal/{{dealId}}"
}
```
### 4. Idempotency for Contracts
Prevent duplicate contracts:
```json
{
"metadata": {
"hubspot_deal_id": "{{input.objectId}}",
"created_at": "{{now}}"
}
}
```
## Getting Started
1. **[Deal Sync Tutorial](/docs/tutorials/deal-sync)** - Start with contract automation
2. **[HubSpot Integration Guide](/docs/integrations/crm/hubspot)** - Set up your CRM connection
3. **[PandaDoc Integration Guide](/docs/integrations/documents/pandadoc)** - Connect document generation
4. **[Slack Block Reference](/docs/workflows/building-blocks/slack-block)** - Learn notification patterns
## Related Resources
- [Invoice Automation Tutorial](/docs/tutorials/invoice-automation)
- [Salesforce Integration Guide](/docs/integrations/crm/salesforce)
- [Email Block Reference](/docs/workflows/building-blocks/email-block)
- [Finance Team Use Cases](/docs/use-cases/finance-teams)
# Workflows (/docs/workflows)
Learn how to build and manage workflows
## Workflows
Workflows are the core building blocks of the Workflows API. A workflow defines a series of steps that execute in response to a trigger.
A good workflow is explicit about what starts it, what data it expects, which systems it touches, and what should happen when something does not match the happy path. In Loopfour, the trigger supplies the initial context, steps transform or act on that context, and each run records the decisions and outputs produced along the way. This structure is especially important for finance processes because later review often matters as much as successful execution.
When designing a workflow, start with the business outcome rather than the integration list. Decide whether the goal is to create an invoice, reconcile a payment, route an approval, update a customer record, notify an owner, or prepare data for another system. Then model the smallest reliable path to that outcome. Add branches only where the process truly differs, and name steps in terms finance operators can recognize. Clear step names make run history easier to audit and support.
Before activating a workflow, review how it behaves when required data is missing, a provider is unavailable, or an approval owner does not respond. Those paths should be intentional. A workflow that only works for perfect input will create manual cleanup later; a workflow with explicit validation and exception handling can fail in a way operators understand and recover from safely.
## Workflow Structure
```json
{
"name": "My Workflow",
"description": "Optional description",
"trigger": { "type": "api" },
"steps": [
{ "id": "step1", "type": "action", "..." }
]
}
```
## Sections
Core concepts and workflow lifecycle
How workflows are started
Actions, conditions, transforms, and waits
Reusable workflow components
# Building Blocks (/docs/workflows/building-blocks)
Reusable workflow components
## Building Blocks
Building blocks are pre-configured step types that simplify common operations.
Use building blocks when a workflow needs a repeatable interaction that should not be rebuilt from raw code each time. Blocks wrap common provider operations, messaging patterns, and workflow behaviors behind a typed configuration surface. That makes them easier to review, easier to validate, and safer to reuse across workflows that share the same operational pattern.
In finance workflows, blocks are useful for the parts of the process that should remain consistent: sending an approval request, posting a Slack notification, formatting an email, transforming data into a provider payload, or creating a record in an external system. Choose the most specific block that matches the job. A specific block usually gives better validation, clearer run logs, and fewer hidden assumptions than a generic code step. Use custom code only when the workflow needs logic that is not already covered by a block or provider action.
Blocks also make workflow review easier. A reviewer can see that one step sends a message, another writes to an accounting system, and another waits for approval without reading custom implementation code. That clarity matters when finance, operations, and engineering share responsibility for the same automation. Prefer predictable blocks for routine work, then reserve flexible steps for exceptional logic that has no reusable provider action yet.
Send messages and interact with Slack
Send emails with template support
# Email Block (/docs/workflows/building-blocks/email-block)
Send emails with Handlebars template support across multiple providers
## Email Block
The Email block sends emails with full Handlebars template support, working across Gmail, Outlook, and Resend.
## Overview
Use the Email block when you need to:
- Send transactional emails (invoices, receipts, notifications)
- Create dynamic email content with templates
- Attach files to emails
- Schedule emails for later delivery
- Support multiple email providers with a unified interface
## Prerequisites
| Provider | Connection Type | Requirements |
|----------|-----------------|--------------|
| Gmail | OAuth via Nango | `gmail` provider configured |
| Outlook | OAuth via Nango | `microsoft-graph` provider configured |
| Resend | API Key | `RESEND_API_KEY` env var or `api_key` in config |
## Configuration
### Step Definition
```json
{
"id": "send-invoice-email",
"type": "email",
"name": "Send Invoice Email",
"config": {
"action": "send",
"provider": "gmail",
"to": "{{input.customer_email}}",
"subject": "Invoice #{{input.invoice_number}} Ready",
"body": {
"html": "Hello {{input.customer_name}},
Your invoice is ready.
"
}
}
}
```
### Configuration Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `action` | string | Yes | `send`, `sendTemplate`, or `schedule` |
| `provider` | string | Yes | `gmail`, `outlook`, or `resend` |
| `to` | string/array | Yes | Recipient email address(es) |
| `subject` | string | Yes | Email subject line |
| `body` | object | Yes* | Email content (`html` and/or `text`) |
| `layout` | string | No | `branded` (default) wraps the HTML body in the Loopfour template; `none` sends the HTML as written |
| `from` | string | No | Sender address (provider-dependent) |
| `cc` | array | No | CC recipients |
| `bcc` | array | No | BCC recipients |
| `reply_to` | string | No | Reply-to address |
| `attachments` | array | No | File attachments |
| `template` | object | No | Server-side template config (see `sendTemplate` below) |
| `send_at` | string | No | Schedule time (ISO 8601) |
## Email Layout
By default, HTML bodies are wrapped in the branded Loopfour email template: a
600px centered card with the Loopfour wordmark, a header, and a footer. This
keeps workflow emails visually consistent with the approval, verification, and
password-reset emails the product sends.
The `layout` field controls this behavior:
- `branded` (default) — wraps the HTML body in the Loopfour template. A body
that is already a complete HTML document (it starts with `` or an
`` tag) is detected and sent as-is, so a full custom document is never
wrapped inside another.
- `none` — sends the HTML exactly as written, with no template applied.
Plain-text bodies (`body.text`) are never modified by either setting.
```json
{
"id": "send-plain-html",
"type": "email",
"config": {
"action": "send",
"provider": "resend",
"to": "{{input.customer_email}}",
"subject": "Invoice #{{input.invoice_number}}",
"layout": "none",
"body": {
"html": "Your invoice is ready.
"
}
}
}
```
## Available Actions
### send
Send an email immediately.
```json
{
"id": "send-notification",
"type": "email",
"config": {
"action": "send",
"provider": "gmail",
"to": "{{input.recipient_email}}",
"cc": ["manager@company.com"],
"subject": "Order Confirmation - #{{input.order_id}}",
"body": {
"html": "Thank you for your order!
Order #{{input.order_id}} has been confirmed.
",
"text": "Thank you for your order! Order #{{input.order_id}} has been confirmed."
},
"reply_to": "support@company.com"
}
}
```
**Output:**
```json
{
"id": "msg_abc123",
"threadId": "thread_xyz789",
"labelIds": ["SENT"]
}
```
### sendTemplate
The `sendTemplate` action is accepted by the step schema, but none of Gmail,
Outlook, or Resend exposes a server-side template API — the step fails at run
time on all three with `does not support server-side templates`. Use the `send`
action with inline Handlebars templates instead.
### schedule
Schedule an email for later delivery (Resend).
```json
{
"id": "schedule-reminder",
"type": "email",
"config": {
"action": "schedule",
"provider": "resend",
"to": "{{input.user_email}}",
"subject": "Reminder: {{input.reminder_title}}",
"body": {
"html": "This is your scheduled reminder for: {{input.reminder_title}}
"
},
"send_at": "{{input.reminder_time}}"
}
}
```
**Note:** Gmail and Outlook do not support native email scheduling. For these providers, use Trigger.dev scheduled tasks instead.
## Handlebars Templates
The Email block uses Handlebars for dynamic content rendering. Templates are processed before sending.
### Basic Variables
```html
Hello {{input.customer_name}},
Your invoice #{{input.invoice_number}} for ${{input.amount}} is ready.
```
### Conditionals
```html
{{#if input.is_overdue}}
This invoice is overdue. Please pay immediately.
{{else}}
Payment is due by {{input.due_date}}.
{{/if}}
```
### Loops
```html
| Item |
Quantity |
Price |
{{#each input.line_items}}
| {{this.description}} |
{{this.quantity}} |
${{this.unit_price}} |
{{/each}}
Total: ${{input.total}}
```
### Nested Properties
```html
Company: {{input.customer.company_name}}
Contact: {{input.customer.contact.first_name}} {{input.customer.contact.last_name}}
Address: {{input.customer.address.street}}, {{input.customer.address.city}}
```
### Using Step Outputs
```html
Your order has been processed.
Transaction ID: {{steps.process-payment.output.transaction_id}}
Amount Charged: ${{steps.process-payment.output.amount}}
```
## Attachments
Attach files to emails using base64-encoded content.
```json
{
"id": "send-with-attachment",
"type": "email",
"config": {
"action": "send",
"provider": "gmail",
"to": "{{input.recipient}}",
"subject": "Monthly Report - {{input.month}}",
"body": {
"html": "Please find the monthly report attached.
"
},
"attachments": [
{
"filename": "report-{{input.month}}.pdf",
"content": "{{input.pdf_base64}}",
"content_type": "application/pdf"
},
{
"filename": "data.csv",
"content": "{{steps.generate-csv.output.csv_base64}}",
"content_type": "text/csv"
}
]
}
}
```
**Attachment Fields:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `filename` | string | Yes | Name of the attached file |
| `content` | string | Yes | Base64-encoded file content |
| `content_type` | string | No | MIME type (default: `application/octet-stream`) |
## Provider-Specific Features
### Gmail
- Uses RFC 2822 message format
- OAuth authentication via `gmail` provider
- Supports threading with `in_reply_to` and `references`
- No native scheduling support
```json
{
"config": {
"provider": "gmail",
"in_reply_to": "{{input.original_message_id}}",
"references": ["{{input.thread_message_id}}"],
"headers": {
"X-Custom-Header": "custom-value"
}
}
}
```
### Outlook
- Uses Microsoft Graph API
- OAuth authentication via `microsoft-graph` provider
- Supports priority levels
- No native scheduling support
```json
{
"config": {
"provider": "outlook",
"priority": "1"
}
}
```
**Priority Values:**
- `1` or `2` = High importance
- `3` = Normal importance (default)
- `4` or `5` = Low importance
### Resend
- Simple, developer-friendly API
- Native email scheduling
- Direct API calls (no Nango)
- Uses the platform Resend key by default; to send from your own Resend account, set `api_key` to a workflow secret: `{{ secrets.RESEND_API_KEY }}`
```json
{
"config": {
"provider": "resend",
"api_key": "{{ secrets.RESEND_API_KEY }}",
"from": "notifications@yourdomain.com",
"send_at": "2024-12-25T09:00:00Z"
}
}
```
**Note:** Resend does not support server-side templates. Use inline Handlebars templates instead.
## Template Variables Reference
| Variable | Description |
|----------|-------------|
| `{{input.field}}` | Workflow trigger input data |
| `{{steps.stepId.output.field}}` | Output from previous step |
| `{{variables.name}}` | Loop variables (the item and index a loop binds); empty outside a loop |
| `{{ secrets.NAME }}` | Workflow secrets, injected at dispatch |
| `{{template_variables.field}}` | Step-specific template variables |
### Providing Additional Variables
Use `template_variables` to pass extra data for template rendering:
```json
{
"config": {
"action": "send",
"provider": "gmail",
"to": "{{input.email}}",
"subject": "Welcome to {{company_name}}",
"body": {
"html": "Welcome to {{company_name}}!
Your account: {{account_type}}
"
},
"template_variables": {
"company_name": "Acme Corp",
"account_type": "Premium"
}
}
}
```
## Error Handling
### Common Errors
| Error | Cause | Solution |
|-------|-------|----------|
| `connectionId is required` | Missing OAuth connection | Ensure provider connection exists |
| `Failed to render template` | Invalid Handlebars syntax | Check template for syntax errors |
| `Unsupported email provider` | Invalid provider value | Use `gmail`, `outlook`, or `resend` |
| `template is required` | Missing template for sendTemplate | Provide template.id for sendTemplate action |
| `send_at is required` | Missing schedule time | Provide ISO 8601 datetime for schedule action |
| `Resend API error` | Invalid API key or request | Check RESEND_API_KEY and request payload |
### Provider-Specific Errors
**Gmail:**
```json
{
"error": {
"code": 403,
"message": "Request had insufficient authentication scopes"
}
}
```
## Rate Limits
| Provider | Limit | Notes |
|----------|-------|-------|
| Gmail | 100 emails/day (free), 2,000/day (Workspace) | Per user quota |
| Outlook | 30 messages/minute | Per mailbox |
| Resend | 100/day (free), 50,000/month (Pro) | Based on plan |
## Related Blocks
- [Slack Block](/docs/workflows/building-blocks/slack-block) - Send Slack notifications
- [Action Steps](/docs/workflows/steps/actions) - Other integration actions
- [Transform Steps](/docs/workflows/steps/transforms) - Data transformation
## Example Workflows
### Invoice Email Workflow
```json
{
"name": "Send Invoice on Payment Due",
"trigger": {
"type": "webhook",
"provider": "quickbooks",
"events": ["invoice.created"]
},
"steps": [
{
"id": "get-customer",
"type": "action",
"action": "quickbooks.getCustomer",
"config": {
"customerId": "{{input.payload.CustomerRef.value}}"
}
},
{
"id": "send-invoice-email",
"type": "email",
"config": {
"action": "send",
"provider": "gmail",
"to": "{{steps.get-customer.output.PrimaryEmailAddr.Address}}",
"subject": "Invoice #{{input.payload.DocNumber}} from Acme Corp",
"body": {
"html": "Invoice #{{input.payload.DocNumber}}
Dear {{steps.get-customer.output.DisplayName}},
Please find your invoice for ${{input.payload.TotalAmt}}.
Due Date: {{input.payload.DueDate}}
View Invoice
Thank you for your business!
"
},
"reply_to": "billing@acme.com"
}
},
{
"id": "notify-sales",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "#billing",
"text": "Invoice #{{input.payload.DocNumber}} sent to {{steps.get-customer.output.DisplayName}}"
}
}
]
}
```
### Welcome Email with Attachment
```json
{
"name": "Send Welcome Email",
"trigger": {
"type": "webhook",
"provider": "hubspot",
"events": ["contact.creation"]
},
"steps": [
{
"id": "generate-welcome-pdf",
"type": "action",
"action": "documents.generatePdf",
"config": {
"template": "welcome-guide",
"data": {
"name": "{{input.properties.firstname}}",
"company": "{{input.properties.company}}"
}
}
},
{
"id": "send-welcome",
"type": "email",
"config": {
"action": "send",
"provider": "resend",
"to": "{{input.properties.email}}",
"from": "welcome@company.com",
"subject": "Welcome to Company, {{input.properties.firstname}}!",
"body": {
"html": "Welcome, {{input.properties.firstname}}!
We're excited to have you on board.
Please find your welcome guide attached.
If you have any questions, reply to this email.
"
},
"attachments": [
{
"filename": "welcome-guide.pdf",
"content": "{{steps.generate-welcome-pdf.output.pdf_base64}}",
"content_type": "application/pdf"
}
]
}
}
]
}
```
### Scheduled Payment Reminder
```json
{
"name": "Schedule Payment Reminder",
"trigger": {
"type": "api"
},
"steps": [
{
"id": "calculate-reminder-time",
"type": "transform",
"config": {
"operation": "map",
"data": {
"reminder_time": "{{input.due_date | dateAdd: -3, 'days'}}"
}
}
},
{
"id": "schedule-reminder",
"type": "email",
"config": {
"action": "schedule",
"provider": "resend",
"to": "{{input.customer_email}}",
"from": "reminders@company.com",
"subject": "Payment Reminder: Invoice #{{input.invoice_number}}",
"body": {
"html": "Hello {{input.customer_name}},
This is a friendly reminder that invoice #{{input.invoice_number}} for ${{input.amount}} is due on {{input.due_date}}.
Pay Now
"
},
"send_at": "{{steps.calculate-reminder-time.output.reminder_time}}"
}
}
]
}
```
# Slack Block (/docs/workflows/building-blocks/slack-block)
Send messages, manage channels, and interact with Slack
## Slack Block
The Slack block provides comprehensive access to Slack messaging, channels, modals, and interactive components within your workflows.
## Overview
Use the Slack block when you need to:
- Send notifications to channels or users
- Create approval workflows with interactive buttons
- Build rich messages with Block Kit
- Manage channels and users programmatically
- Upload files and add reactions
## Prerequisites
- **Slack Connection**: Configure OAuth via Nango with `slack` provider
- **Bot Permissions**: Bot must be added to target channels
- **Scopes Required**: Varies by action (see action-specific requirements)
## Configuration
### Step Definition
```json
{
"id": "notify-team",
"type": "slack",
"name": "Send Team Notification",
"config": {
"action": "sendMessage",
"channel": "#billing",
"text": "Invoice {{input.invoice_number}} has been paid!"
}
}
```
### Configuration Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `action` | string | Yes | The Slack action to execute |
| `channel` | string | Varies | Channel ID or name (e.g., `#general`, `C1234567890`) |
| `text` | string | Varies | Message text (supports mrkdwn) |
| `blocks` | array | Varies | Block Kit blocks for rich layouts |
| `user` | string | Varies | User ID for user-specific actions |
## Available Actions
### Message Actions
#### sendMessage
Send a message to a channel or DM.
**Required Scopes**: `chat:write`, `chat:write.public` (for non-member channels)
```json
{
"id": "send-notification",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "#sales",
"text": "New deal closed: {{input.deal_name}} for ${{input.amount}}",
"threadTs": "{{input.parent_message_ts}}",
"unfurlLinks": false,
"mrkdwn": true
}
}
```
**Parameters:**
| Field | Type | Description |
|-------|------|-------------|
| `channel` | string | Channel ID or name |
| `text` | string | Message text (required if no blocks) |
| `blocks` | array | Block Kit blocks |
| `threadTs` | string | Reply to thread |
| `replyBroadcast` | boolean | Also post to channel when replying |
| `unfurlLinks` | boolean | Enable link previews |
| `unfurlMedia` | boolean | Enable media previews |
| `mrkdwn` | boolean | Enable mrkdwn formatting (default: true) |
| `attachments` | array | Legacy attachments |
| `metadata` | object | Message metadata |
**Output:**
```json
{
"ok": true,
"channel": "C1234567890",
"ts": "1234567890.123456",
"message": {
"text": "New deal closed...",
"user": "U1234567890",
"ts": "1234567890.123456"
}
}
```
#### sendEphemeral
Send an ephemeral message (only visible to one user).
**Required Scopes**: `chat:write`
```json
{
"id": "private-hint",
"type": "slack",
"config": {
"action": "sendEphemeral",
"channel": "#general",
"user": "{{input.user_id}}",
"text": "Only you can see this message!"
}
}
```
**Parameters:**
| Field | Type | Description |
|-------|------|-------------|
| `channel` | string | Channel ID |
| `user` | string | User ID to show message to |
| `text` | string | Message text |
| `blocks` | array | Block Kit blocks |
| `threadTs` | string | Thread timestamp |
#### scheduleMessage
Schedule a message to be sent later.
**Required Scopes**: `chat:write`
```json
{
"id": "schedule-reminder",
"type": "slack",
"config": {
"action": "scheduleMessage",
"channel": "#reminders",
"text": "Don't forget: {{input.reminder_text}}",
"postAt": "{{input.reminder_time}}"
}
}
```
**Parameters:**
| Field | Type | Description |
|-------|------|-------------|
| `channel` | string | Channel ID |
| `postAt` | number/string | Unix timestamp or ISO 8601 datetime |
| `text` | string | Message text |
| `blocks` | array | Block Kit blocks |
**Output:**
```json
{
"ok": true,
"channel": "C1234567890",
"scheduled_message_id": "Q1234567890",
"post_at": 1234567890
}
```
#### updateMessage
Update an existing message.
**Required Scopes**: `chat:write`
```json
{
"id": "update-status",
"type": "slack",
"config": {
"action": "updateMessage",
"channel": "{{steps.send-message.output.channel}}",
"ts": "{{steps.send-message.output.ts}}",
"text": "Status: Completed!"
}
}
```
**Parameters:**
| Field | Type | Description |
|-------|------|-------------|
| `channel` | string | Channel ID |
| `ts` | string | Message timestamp to update |
| `text` | string | New message text |
| `blocks` | array | New Block Kit blocks |
#### deleteMessage
Delete a message.
**Required Scopes**: `chat:write`
```json
{
"id": "cleanup-message",
"type": "slack",
"config": {
"action": "deleteMessage",
"channel": "{{input.channel_id}}",
"ts": "{{input.message_ts}}"
}
}
```
#### getPermalink
Get a permanent link to a message.
```json
{
"id": "get-link",
"type": "slack",
"config": {
"action": "getPermalink",
"channel": "{{input.channel_id}}",
"messageTs": "{{input.message_ts}}"
}
}
```
**Output:**
```json
{
"ok": true,
"channel": "C1234567890",
"permalink": "https://workspace.slack.com/archives/C1234567890/p1234567890123456"
}
```
### Reaction Actions
#### addReaction
Add an emoji reaction to a message.
**Required Scopes**: `reactions:write`
```json
{
"id": "react-to-message",
"type": "slack",
"config": {
"action": "addReaction",
"channel": "{{input.channel_id}}",
"timestamp": "{{input.message_ts}}",
"name": "white_check_mark"
}
}
```
**Parameters:**
| Field | Type | Description |
|-------|------|-------------|
| `channel` | string | Channel ID |
| `timestamp` | string | Message timestamp |
| `name` | string | Emoji name (without colons) |
#### removeReaction
Remove an emoji reaction.
```json
{
"id": "remove-reaction",
"type": "slack",
"config": {
"action": "removeReaction",
"channel": "{{input.channel_id}}",
"timestamp": "{{input.message_ts}}",
"name": "eyes"
}
}
```
### File Actions
#### uploadFile
Upload a file to Slack.
**Required Scopes**: `files:write`
```json
{
"id": "upload-report",
"type": "slack",
"config": {
"action": "uploadFile",
"channels": ["#reports", "#finance"],
"content": "{{input.csv_content}}",
"filename": "report-{{input.date}}.csv",
"title": "Monthly Report",
"initialComment": "Here's the monthly report!"
}
}
```
**Parameters:**
| Field | Type | Description |
|-------|------|-------------|
| `channels` | string/array | Channel(s) to share file |
| `content` | string | Text content for the file |
| `file` | string | Base64 encoded file content |
| `filename` | string | Name of the file |
| `filetype` | string | File type (e.g., `csv`, `pdf`) |
| `title` | string | Title of the file |
| `initialComment` | string | Comment to add with file |
| `threadTs` | string | Thread to upload to |
#### getFile
Get file information.
```json
{
"id": "get-file-info",
"type": "slack",
"config": {
"action": "getFile",
"fileId": "{{input.file_id}}"
}
}
```
#### deleteFile
Delete a file.
```json
{
"id": "delete-file",
"type": "slack",
"config": {
"action": "deleteFile",
"fileId": "{{input.file_id}}"
}
}
```
### Modal/View Actions
#### openModal
Open a modal view (requires trigger_id from interactive event).
**Required Scopes**: None (uses bot token)
```json
{
"id": "open-approval-modal",
"type": "slack",
"config": {
"action": "openModal",
"triggerId": "{{input.trigger_id}}",
"view": {
"type": "modal",
"title": { "type": "plain_text", "text": "Approve Request" },
"submit": { "type": "plain_text", "text": "Approve" },
"close": { "type": "plain_text", "text": "Cancel" },
"blocks": [
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "Approve invoice #{{input.invoice_number}}?"
}
},
{
"type": "input",
"block_id": "notes_block",
"element": {
"type": "plain_text_input",
"action_id": "notes_input",
"multiline": true,
"placeholder": { "type": "plain_text", "text": "Add notes..." }
},
"label": { "type": "plain_text", "text": "Notes" }
}
]
}
}
}
```
**Parameters:**
| Field | Type | Description |
|-------|------|-------------|
| `triggerId` | string | Trigger ID from interactive event |
| `view` | object | Modal view definition |
#### updateModal
Update an existing modal.
```json
{
"id": "update-modal",
"type": "slack",
"config": {
"action": "updateModal",
"viewId": "{{input.view_id}}",
"view": {
"type": "modal",
"title": { "type": "plain_text", "text": "Updated Modal" },
"blocks": [...]
}
}
}
```
**Parameters:**
| Field | Type | Description |
|-------|------|-------------|
| `viewId` | string | View ID to update |
| `externalId` | string | Alternative: external ID |
| `view` | object | Updated view definition |
| `hash` | string | Optional hash for conflict detection |
#### pushModal
Push a new view onto the modal stack.
```json
{
"id": "push-details",
"type": "slack",
"config": {
"action": "pushModal",
"triggerId": "{{input.trigger_id}}",
"view": {
"type": "modal",
"title": { "type": "plain_text", "text": "Details" },
"blocks": [...]
}
}
}
```
#### publishHomeTab
Publish content to a user's Home tab.
**Required Scopes**: None (uses bot token)
```json
{
"id": "update-home",
"type": "slack",
"config": {
"action": "publishHomeTab",
"userId": "{{input.user_id}}",
"view": {
"type": "home",
"blocks": [
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "Welcome, *{{input.user_name}}*!"
}
},
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "You have {{input.pending_count}} pending approvals."
}
}
]
}
}
}
```
### User Actions
#### getUser
Get user information.
**Required Scopes**: `users:read`
```json
{
"id": "get-user",
"type": "slack",
"config": {
"action": "getUser",
"userId": "{{input.user_id}}",
"includeLocale": true
}
}
```
**Output:**
```json
{
"ok": true,
"user": {
"id": "U1234567890",
"name": "johndoe",
"real_name": "John Doe",
"profile": {
"email": "john@example.com",
"display_name": "John"
}
}
}
```
#### listUsers
List workspace users.
**Required Scopes**: `users:read`
```json
{
"id": "list-users",
"type": "slack",
"config": {
"action": "listUsers",
"limit": 100,
"includeLocale": false
}
}
```
#### lookupUserByEmail
Find a user by email address.
**Required Scopes**: `users:read.email`
```json
{
"id": "find-user",
"type": "slack",
"config": {
"action": "lookupUserByEmail",
"email": "{{input.email}}"
}
}
```
### Channel Actions
#### getChannel
Get channel information.
**Required Scopes**: `channels:read`, `groups:read`
```json
{
"id": "get-channel",
"type": "slack",
"config": {
"action": "getChannel",
"channelId": "{{input.channel_id}}",
"includeNumMembers": true
}
}
```
#### listChannels
List channels.
**Required Scopes**: `channels:read`, `groups:read`
```json
{
"id": "list-channels",
"type": "slack",
"config": {
"action": "listChannels",
"types": "public_channel,private_channel",
"excludeArchived": true,
"limit": 100
}
}
```
**Parameters:**
| Field | Type | Description |
|-------|------|-------------|
| `types` | string | Channel types (public_channel, private_channel, mpim, im) |
| `excludeArchived` | boolean | Exclude archived channels (default: true) |
| `limit` | number | Max results (default: 100) |
| `cursor` | string | Pagination cursor |
#### createChannel
Create a new channel.
**Required Scopes**: `channels:manage`, `groups:write`
```json
{
"id": "create-project-channel",
"type": "slack",
"config": {
"action": "createChannel",
"name": "proj-{{input.project_slug}}",
"isPrivate": false
}
}
```
#### inviteToChannel
Invite users to a channel.
**Required Scopes**: `channels:manage`, `groups:write`
```json
{
"id": "invite-team",
"type": "slack",
"config": {
"action": "inviteToChannel",
"channelId": "{{steps.create-channel.output.channel.id}}",
"users": ["U111111", "U222222", "U333333"]
}
}
```
#### archiveChannel
Archive a channel.
```json
{
"id": "archive-channel",
"type": "slack",
"config": {
"action": "archiveChannel",
"channelId": "{{input.channel_id}}"
}
}
```
#### setChannelTopic
Set channel topic.
```json
{
"id": "set-topic",
"type": "slack",
"config": {
"action": "setChannelTopic",
"channelId": "{{input.channel_id}}",
"topic": "Project: {{input.project_name}} | Status: {{input.status}}"
}
}
```
#### getChannelHistory
Get channel message history.
**Required Scopes**: `channels:history`, `groups:history`
```json
{
"id": "get-history",
"type": "slack",
"config": {
"action": "getChannelHistory",
"channelId": "{{input.channel_id}}",
"limit": 50,
"oldest": "{{input.since_timestamp}}"
}
}
```
### Bookmark Actions
#### addBookmark
Add a bookmark to a channel.
**Required Scopes**: `bookmarks:write`
```json
{
"id": "add-bookmark",
"type": "slack",
"config": {
"action": "addBookmark",
"channelId": "{{input.channel_id}}",
"title": "Project Dashboard",
"type": "link",
"link": "https://dashboard.example.com/{{input.project_id}}"
}
}
```
## Block Kit Examples
### Rich Notification with Buttons
```json
{
"id": "approval-request",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "#approvals",
"text": "New approval request",
"blocks": [
{
"type": "header",
"text": { "type": "plain_text", "text": "Invoice Approval Required" }
},
{
"type": "section",
"fields": [
{ "type": "mrkdwn", "text": "*Invoice:*\n#{{input.invoice_number}}" },
{ "type": "mrkdwn", "text": "*Amount:*\n${{input.amount}}" },
{ "type": "mrkdwn", "text": "*Vendor:*\n{{input.vendor_name}}" },
{ "type": "mrkdwn", "text": "*Due Date:*\n{{input.due_date}}" }
]
},
{
"type": "actions",
"block_id": "approval_actions",
"elements": [
{
"type": "button",
"text": { "type": "plain_text", "text": "Approve" },
"action_id": "approve_invoice",
"style": "primary",
"value": "{{input.invoice_id}}"
},
{
"type": "button",
"text": { "type": "plain_text", "text": "Reject" },
"action_id": "reject_invoice",
"style": "danger",
"value": "{{input.invoice_id}}"
},
{
"type": "button",
"text": { "type": "plain_text", "text": "View Details" },
"action_id": "view_invoice",
"url": "https://app.example.com/invoices/{{input.invoice_id}}"
}
]
}
]
}
}
```
### Status Update with Context
```json
{
"id": "pipeline-status",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "#deployments",
"blocks": [
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "{{#if input.success}}:white_check_mark:{{else}}:x:{{/if}} *Build {{input.build_number}}* {{input.status}}"
}
},
{
"type": "context",
"elements": [
{ "type": "mrkdwn", "text": "Branch: `{{input.branch}}`" },
{ "type": "mrkdwn", "text": "Commit: `{{input.commit_sha}}`" },
{ "type": "mrkdwn", "text": "Duration: {{input.duration}}s" }
]
}
]
}
}
```
## Template Variables
Access workflow data in your Slack configuration:
| Variable | Description |
|----------|-------------|
| `{{input.field}}` | Workflow trigger input |
| `{{steps.stepId.output.field}}` | Previous step output |
| `{{variables.name}}` | Loop variables (the item and index a loop binds); empty outside a loop |
| `{{ secrets.NAME }}` | Workflow secrets, injected at dispatch |
## Error Handling
### Common Errors
| Error | Cause | Solution |
|-------|-------|----------|
| `channel_not_found` | Invalid channel ID/name | Verify channel exists and bot has access |
| `not_in_channel` | Bot not in channel | Invite bot to channel or use `chat:write.public` |
| `invalid_blocks` | Malformed Block Kit | Validate blocks with Block Kit Builder |
| `trigger_expired` | Stale trigger_id | Trigger IDs expire in 3 seconds |
| `missing_scope` | Insufficient permissions | Add required OAuth scopes |
| `rate_limited` | Too many requests | Implement backoff, respect retry-after |
### Error Response
```json
{
"ok": false,
"error": "channel_not_found",
"response_metadata": {
"messages": ["Channel not found or bot not a member"]
}
}
```
## Rate Limits
| Tier | Limit | Description |
|------|-------|-------------|
| Tier 1 | 1/min | Low-frequency methods |
| Tier 2 | 20/min | Most methods |
| Tier 3 | 50/min | High-frequency methods |
| Tier 4 | 100/min | Very high-frequency |
| Special | Varies | chat.postMessage: ~1/sec per channel |
Slack returns `429 Too Many Requests` with `Retry-After` header when limits are exceeded.
## Related Blocks
- [Email Block](/docs/workflows/building-blocks/email-block) - Send email notifications
- [Action Steps](/docs/workflows/steps/actions) - Other integration actions
- [Condition Steps](/docs/workflows/steps/conditions) - Conditional logic
## Example Workflow
Complete approval workflow with Slack:
```json
{
"name": "Invoice Approval Workflow",
"trigger": {
"type": "webhook",
"provider": "quickbooks",
"events": ["invoice.created"]
},
"steps": [
{
"id": "check-amount",
"type": "condition",
"config": {
"conditions": {
"left": "{{input.payload.TotalAmt}}",
"operator": "gt",
"right": 1000
},
"then": ["request-approval"],
"else": ["auto-approve"]
}
},
{
"id": "request-approval",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "#finance-approvals",
"text": "Invoice requires approval",
"blocks": [
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "*New Invoice Requires Approval*\n\nAmount: ${{input.payload.TotalAmt}}\nVendor: {{input.payload.CustomerRef.name}}"
}
},
{
"type": "actions",
"elements": [
{
"type": "button",
"text": { "type": "plain_text", "text": "Approve" },
"action_id": "approve_{{input.payload.Id}}",
"style": "primary"
},
{
"type": "button",
"text": { "type": "plain_text", "text": "Reject" },
"action_id": "reject_{{input.payload.Id}}",
"style": "danger"
}
]
}
]
}
},
{
"id": "auto-approve",
"type": "slack",
"config": {
"action": "sendMessage",
"channel": "#finance-log",
"text": ":white_check_mark: Auto-approved invoice #{{input.payload.DocNumber}} for ${{input.payload.TotalAmt}}"
}
}
]
}
```
# Workflow recipe templates (/docs/workflows/dashboard-templates)
How the template tiles map to canonical workflow templates, and how to add a new one.
## Workflow recipe templates
The tiles on the chat home (`/chat`) and the gallery (`/workflows?tab=templates`)
are both backed by the same **system templates** — rows in `workflow_templates`
with `company_id IS NULL` and a stable `slug` (e.g. `cash-application`).
## How the pieces fit
```
packages/db/src/templates/recipes/.ts ← canonical workflow JSON
│ (compile-time registry: DASHBOARD_TEMPLATE_DEFINITIONS)
▼
bun run db:seed:template-recipes ← upserts into workflow_templates
│
▼
GET /api/v1/templates/by-slug/:slug ← chat home / chat tools resolve here
GET /api/v1/templates/gallery ← gallery list
```
Slugs are unique among system templates (`UNIQUE (slug) WHERE company_id IS NULL`).
They never change across environments — a UUID is generated by Postgres on insert
and may differ between dev/staging/prod, but the slug is authored in code and is
identical everywhere the seeder runs.
## Adding a new workflow recipe template
Three small changes:
### 1. Card metadata
Add the tile entry in `apps/studio/lib/templates/gallery-registry.ts`:
```ts
{
id: "ap-payment-batching", // kebab-case, must be unique
title: "AP payment batching",
description: "...",
category: "ap", // ar | ap | billing | close | revrec
metaItems: ["Bill.com", "Daily"],
integrations: integrations("billcom"),
previewSteps: ["Pull approved bills", "Group by vendor", "Queue ACH"],
prompt: "Build a workflow that ...",
live: true,
}
```
### 2. Canonical JSON
Drop a new file in `packages/db/src/templates/recipes/.ts`:
```ts
export const apPaymentBatchingTemplate = defineDashboardTemplate({
templateId: "ap-payment-batching",
name: "AP payment batching",
description: "...",
category: "finance",
tags: ["dashboard-card", "ap"],
requiredConnections: ["billcom"],
variables: [],
trigger: { type: "schedule", cron: "0 8 * * *", timezone: "UTC", enabled: true },
steps: [
{ id: "pull_bills", type: "action", name: "Pull approved bills", action: "billcom.listApprovedBills", config: {} },
// …
],
});
```
`defineDashboardTemplate` is an identity helper that pins the literal `templateId`
type and throws at module-load time if a duplicate slug is registered.
### 3. Registry index
Import and register in `packages/db/src/templates/recipes/index.ts`:
```ts
export const DASHBOARD_TEMPLATE_DEFINITIONS = {
// …
"ap-payment-batching": apPaymentBatchingTemplate,
} as const satisfies Record;
```
The `Record` constraint in Studio fails the build if a
card id has no matching template, so missing this step is caught at compile time.
## Deploying
After committing template changes:
```bash
bun run --filter=@workflows/db db:seed:template-recipes
```
The seeder is idempotent — safe to re-run on every deploy. It upserts on
`(slug) WHERE company_id IS NULL`, preserving each row's UUID and any stars,
just patching mutable fields (name, description, steps, etc.).
## Don't
- **Don't** rename a slug after it ships. Slugs are stable identifiers; renaming
one breaks every reference (chat tools, deep links, audit logs).
- **Don't** set `slug` from `POST /api/v1/templates`. Slugs are seeder-only;
company-specific templates created via the API always have `slug = NULL`.
- **Don't** use the `category` enum to express dashboard subcategories. Category
stays `finance` (the API enum); dashboard subcategories live in `tags`
(`ar`, `ap`, `billing`, `close`, `revrec`).
# Workflow Overview (/docs/workflows/overview)
Core workflow concepts, lifecycle, and execution model
## Workflow Overview
Workflows are the core building blocks of the Workflows API. This guide explains the fundamental concepts you need to understand when building automated processes.
## What is a Workflow?
A **workflow** is a declarative automation that defines:
1. **When** to run (the trigger)
2. **What** to do (the steps)
3. **How** to handle data (variables and templates)
Workflows enable you to:
- **Connect systems** - Integrate Stripe, Salesforce, HubSpot, QuickBooks, and more
- **Transform data** - Map and reshape data between different formats
- **Make decisions** - Branch logic based on conditions
- **Wait for events** - Pause for human approval or external events
- **Handle errors** - Automatic retries with configurable strategies
```mermaid
graph LR
A[Trigger] --> B[Step 1]
B --> C[Step 2]
C --> D{Condition}
D -->|Yes| E[Step 3a]
D -->|No| F[Step 3b]
E --> G[Output]
F --> G
```
## Workflow Lifecycle
Every workflow progresses through a defined set of states:
```mermaid
stateDiagram-v2
[*] --> draft: Create
draft --> active: Activate
active --> paused: Pause
paused --> active: Resume
active --> archived: Archive
paused --> archived: Archive
draft --> archived: Archive
```
| State | Description | Can Execute? | Can Edit? |
|-------|-------------|--------------|-----------|
| `draft` | Initial state after creation | No | Yes |
| `active` | Ready to receive triggers and execute | Yes | Yes (creates new version) |
| `paused` | Temporarily disabled | No | Yes |
| `archived` | Soft deleted | No | No |
### State Transitions
```bash
curl -X POST https://workflow.loopfour.ai/api/v1/workflows/{id}/activate \
-H "x-api-key: YOUR_API_KEY"
```
```bash
curl -X POST https://workflow.loopfour.ai/api/v1/workflows/{id}/pause \
-H "x-api-key: YOUR_API_KEY"
```
```bash
curl -X POST https://workflow.loopfour.ai/api/v1/workflows/{id}/resume \
-H "x-api-key: YOUR_API_KEY"
```
```bash
curl -X DELETE https://workflow.loopfour.ai/api/v1/workflows/{id} \
-H "x-api-key: YOUR_API_KEY"
```
## Workflow Structure
A workflow is defined as a JSON object with these key components:
```json
{
"name": "Invoice on Deal Close",
"description": "Create a QuickBooks invoice when a Salesforce deal is won",
// 1. TRIGGER - When does this workflow run?
"trigger": {
"type": "webhook",
"provider": "salesforce",
"events": ["opportunity.closed_won"]
},
// 2. STEPS - What actions does it perform?
"steps": [
{
"id": "transform-data",
"type": "transform",
"name": "Map Deal to Invoice",
"config": {
"mapping": {
"customer_email": "{{input.account.email}}",
"amount": "{{input.opportunity.amount}}",
"description": "{{input.opportunity.name}}"
}
}
},
{
"id": "create-invoice",
"type": "action",
"name": "Create QuickBooks Invoice",
"config": {
"connector": "quickbooks",
"action": "createInvoice",
"params": {
"customerEmail": "{{steps.transform-data.output.customer_email}}",
"amount": "{{steps.transform-data.output.amount}}",
"memo": "{{steps.transform-data.output.description}}"
}
}
}
],
// 3. VARIABLES - Reusable configuration values
"variables": {
"taxRate": 0.0825,
"defaultTerms": "Net 30"
}
}
```
## Triggers
Triggers define **when** a workflow executes. The Workflows API supports multiple trigger types:
| Type | Description | Use Case |
|------|-------------|----------|
| `webhook` | External system sends an event | Stripe payment, custom webhooks |
| `schedule` | Time-based execution | Daily reports, weekly syncs |
| `api` | Manual execution via API | On-demand processing, testing |
| `salesforce_event` | Salesforce Platform Events or CDC | Record changes, custom events |
| `hubspot_event` | HubSpot property changes | Contact/deal updates |
| `slack_event` | Slack Events API | Messages, mentions, reactions |
| `slack_slash_command` | Slack slash commands | /invoice, /approve |
| `slack_interactive` | Slack interactive components | Button clicks, modal submissions |
| `gmail_event` | Gmail Pub/Sub events | New emails, label changes |
### Webhook Triggers
Webhook triggers listen for events from external providers:
```json
{
"trigger": {
"type": "webhook",
"provider": "stripe",
"events": ["invoice.paid", "invoice.payment_failed"]
}
}
```
Supported providers: `stripe`, `salesforce`, `hubspot`, `quickbooks`, `pandadoc`, `netsuite`, `slack`
See [Webhook Triggers](/docs/triggers/webhook) for provider-specific configuration.
### Schedule Triggers
Schedule triggers use cron expressions for time-based execution:
```json
{
"trigger": {
"type": "schedule",
"cron": "0 9 * * MON",
"timezone": "America/New_York"
}
}
```
See [Schedule Triggers](/docs/triggers/schedule) for cron syntax and examples.
### API Triggers
API triggers allow manual workflow execution:
```json
{
"trigger": {
"type": "api"
}
}
```
```bash
curl -X POST https://workflow.loopfour.ai/api/v1/workflows/{id}/run \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input": {"customer_id": "cus_123"}}'
```
## Steps
Steps define **what** a workflow does. Each step executes sequentially (unless using parallel execution).
### Step Types
| Type | Description | Example |
|------|-------------|---------|
| `action` | Call an integration | Create Stripe invoice, update Salesforce record |
| `transform` | Map and reshape data | Convert webhook payload to invoice format |
| `condition` | Branch based on logic | If amount > $1000, require approval |
| `wait` | Pause execution | Wait 24 hours, delay before retry |
| `parallel` | Execute steps concurrently | Notify Slack AND send email |
| `loop` | Iterate over a collection | Process each line item |
| `approval` | Human-in-the-loop | Wait for manager approval |
| `agent` | AI-powered processing | Extract invoice data, classify expense |
| `code` | Custom JavaScript | Run sandboxed code for complex logic |
| `slack` | Slack building block | Send message, open modal |
| `email` | Email building block | Send templated email |
| `gmail` | Gmail building block | Read/send Gmail messages |
### Step Structure
Every step has this base structure:
```json
{
"id": "unique-step-id",
"type": "action",
"name": "Human-readable name",
"action": "stripe.createInvoice",
"config": {
// Step-specific configuration
},
"retryConfig": {
"maxAttempts": 3,
"initialDelayMs": 1000,
"maxDelayMs": 30000,
"backoffMultiplier": 2
},
"errorHandling": {
"strategy": "fail",
"fallback": {}
},
"timeoutMs": 30000
}
```
See [Steps Documentation](/docs/workflows/steps) for detailed configuration of each step type.
## Template Variables
Template variables allow dynamic data access throughout your workflow using `{{expression}}` syntax.
### Available Contexts
| Context | Syntax | Description |
|---------|--------|-------------|
| Input | `{{input.field}}` | Trigger payload data |
| Steps | `{{steps.stepId.output.field}}` | Previous step outputs |
| Loop variables | `{{variables.name}}` | The item and index a loop binds; empty outside a loop |
| Secrets | `{{ secrets.NAME }}` | Workflow secrets, injected at dispatch |
| System | `{{now}}`, `{{runId}}` | System-provided values |
### Examples
```json
{
"steps": [
{
"id": "send-email",
"type": "action",
"config": {
"connector": "email",
"action": "send",
"params": {
// Access trigger input
"to": "{{input.customer.email}}",
// Access previous step output
"subject": "Invoice #{{steps.create-invoice.output.invoice_number}}",
// A fixed per-workflow value goes in literally
"cc": "finance@example.com",
// Use expressions
"body": "Amount due: ${{input.amount / 100}}"
}
}
}
]
}
```
### Nested Access
Access nested properties using dot notation:
```
{{input.customer.billing.address.city}}
{{steps.fetch-deal.output.opportunity.account.owner.email}}
```
### Conditional Expressions
Use Handlebars-style conditionals in templates:
```
{{#if input.is_priority}}URGENT: {{/if}}New invoice created
```
## Workflow Execution
When a workflow executes, it creates a **run** that tracks the execution state.
```mermaid
sequenceDiagram
participant T as Trigger
participant W as Workflow Engine
participant S1 as Step 1
participant S2 as Step 2
participant DB as Database
T->>W: Event received
W->>DB: Create run (pending)
W->>S1: Execute step
S1-->>W: Output
W->>DB: Update step status
W->>S2: Execute step
S2-->>W: Output
W->>DB: Run completed
```
### Run States
| State | Description |
|-------|-------------|
| `pending` | Run created, waiting to start |
| `running` | Currently executing steps |
| `suspended` | Paused for human approval or external event |
| `completed` | All steps finished successfully |
| `failed` | A step failed after all retries |
| `cancelled` | Manually cancelled |
### Viewing Run History
```bash
# List runs for a workflow
curl "https://workflow.loopfour.ai/api/v1/workflows/{id}/runs" \
-H "x-api-key: YOUR_API_KEY"
# Get run details
curl "https://workflow.loopfour.ai/api/v1/runs/{runId}" \
-H "x-api-key: YOUR_API_KEY"
```
## Error Handling
The Workflows API provides robust error handling at multiple levels.
### Step-Level Retries
Configure automatic retries for transient failures using `retryConfig`:
```json
{
"id": "call-api",
"type": "action",
"config": { ... },
"retryConfig": {
"maxAttempts": 3,
"initialDelayMs": 1000,
"maxDelayMs": 30000,
"backoffMultiplier": 2
}
}
```
| Option | Type | Description |
|--------|------|-------------|
| `maxAttempts` | number | Maximum retry attempts (1-10) |
| `initialDelayMs` | number | Initial delay in milliseconds (min: 100) |
| `maxDelayMs` | number | Maximum delay between retries (min: 1000) |
| `backoffMultiplier` | number | Multiplier for exponential backoff (1-10) |
### Error Strategies
Define how to handle step failures using `errorHandling`:
```json
{
"id": "optional-step",
"type": "action",
"config": { ... },
"errorHandling": {
"strategy": "continue",
"fallback": {
"defaultValue": "N/A"
}
}
}
```
| Strategy | Behavior |
|----------|----------|
| `fail` | Stop workflow, mark run as failed (default) |
| `continue` | Log error, continue to next step |
| `retry` | Retry with configured `retryConfig` settings |
The optional `fallback` object provides default output values when a step fails with `continue` strategy.
### Timeout Configuration
Prevent steps from hanging indefinitely with `timeoutMs`:
```json
{
"id": "slow-api",
"type": "action",
"config": { ... },
"timeoutMs": 60000
}
```
## Versioning
Workflows support version control to track changes over time.
### How Versioning Works
1. **Create** - Initial workflow is version 1
2. **Update** - Each update to an active workflow creates a new version
3. **Execution** - Running workflows complete with their started version
4. **Rollback** - Revert to any previous version
### Version API
```bash
# List versions
curl "https://workflow.loopfour.ai/api/v1/workflows/{id}/versions" \
-H "x-api-key: YOUR_API_KEY"
# Get specific version
curl "https://workflow.loopfour.ai/api/v1/workflows/{id}/versions/3" \
-H "x-api-key: YOUR_API_KEY"
# Rollback to version
curl -X POST "https://workflow.loopfour.ai/api/v1/workflows/{id}/versions/3/rollback" \
-H "x-api-key: YOUR_API_KEY"
```
### Version States
| State | Description |
|-------|-------------|
| `current` | Active version used for new runs |
| `archived` | Previous version, available for rollback |
| `rollback` | Version restored from rollback operation |
## Best Practices
### Naming Conventions
- Use descriptive workflow names: `Invoice Customer on Deal Close`
- Use verb-noun step IDs: `transform-payment`, `send-notification`
- Include context in descriptions
### Idempotency
Design workflows to be safely re-run:
```json
{
"id": "create-or-update",
"type": "action",
"config": {
"connector": "stripe",
"action": "createCustomer",
"params": {
"idempotencyKey": "{{input.deal_id}}"
}
}
}
```
### Error Recovery
- Use appropriate retry counts for each integration
- Set reasonable timeouts
- Use `onError: continue` for non-critical steps
### Testing
- Start with `draft` status for development
- Use API trigger for manual testing
- Check run history for debugging
## Next Steps
Configure webhook, schedule, and API triggers
Learn about actions, conditions, transforms, and more
Connect to Stripe, Salesforce, HubSpot, and more
Build a complete workflow step by step
# Steps (/docs/workflows/steps)
Workflow step types and configuration
## Workflow Steps
Steps are the building blocks of workflows. Each step performs an operation and passes data to subsequent steps.
Think of a step as one reviewable unit of work. It should have a clear input, a clear output, and a name that explains its business purpose. A workflow becomes easier to maintain when each step does one thing: fetch a record, transform fields, test a condition, send a notification, wait for approval, or write the final update. If a step performs several unrelated operations, split it so run logs can show exactly where a workflow succeeded or failed.
Step design matters most when workflows touch money, contracts, invoices, or customer data. A failed provider call should not obscure whether validation already passed. A condition should make its threshold obvious. A transform should preserve the fields needed for later review. When naming and configuring steps, assume that someone outside the implementation team may inspect the run weeks later to answer why a record changed or why an exception was routed to a human.
## Step Types
Execute integration actions
Branch based on conditions
Transform and map data
Pause execution
## Common Properties
All steps share these properties:
```json
{
"id": "unique-step-id",
"type": "action",
"name": "Human-readable name",
"config": { }
}
```
| Property | Required | Description |
|----------|----------|-------------|
| `id` | Yes | Unique identifier for referencing in templates |
| `type` | Yes | Step type (action, condition, transform, wait) |
| `name` | No | Display name for the step |
| `config` | Yes | Type-specific configuration |
# Action Steps (/docs/workflows/steps/actions)
Execute integration actions in workflows
## Action Steps
Action steps execute operations on external services through connectors. They are the primary way to interact with integrated systems like Stripe, Salesforce, HubSpot, QuickBooks, and more.
## Configuration
```json
{
"id": "create-invoice",
"type": "action",
"name": "Create Stripe Invoice",
"action": "stripe.createInvoice",
"config": {
"customerId": "{{input.customer_id}}",
"items": [
{
"price": "price_xxx",
"quantity": 1
}
]
}
}
```
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Unique step identifier |
| `type` | string | Yes | Must be `"action"` |
| `name` | string | Yes | Human-readable name |
| `action` | string | Yes | Action identifier (e.g., `stripe.createInvoice`) |
| `config` | object | Yes | Action-specific configuration |
| `retryConfig` | object | No | Retry configuration |
| `errorHandling` | object | No | Error handling strategy |
| `timeoutMs` | number | No | Timeout in milliseconds |
## Action Format
Actions follow the pattern `{connector}.{actionName}`:
```
stripe.createInvoice
salesforce.updateOpportunity
hubspot.createContact
quickbooks.listCustomers
slack.sendMessage
```
## Available Connectors
| Connector | Description | Example Actions |
|-----------|-------------|-----------------|
| `stripe` | Payment processing | `createInvoice`, `getCustomer`, `createSubscription` |
| `salesforce` | CRM operations | `getAccount`, `updateOpportunity`, `query` |
| `hubspot` | Marketing/CRM | `createContact`, `getDeal`, `searchContacts` |
| `quickbooks` | Accounting | `createInvoice`, `getCustomer`, `createPayment` |
| `pandadoc` | Document signing | `createDocument`, `sendDocument`, `getStatus` |
| `netsuite` | ERP operations | `createCustomer`, `createInvoice`, `suiteql` |
| `slack` | Messaging | `sendMessage`, `openModal`, `addReaction` |
| `email` | Email sending | `send`, `send_template`, `schedule` |
| `api` | Call any HTTP endpoint | `request` |
See [Integrations](/docs/integrations) for complete action documentation per connector.
## API Request Block
When no connector covers the service you need, the core `api` block calls any HTTP
endpoint directly.
```json
{
"id": "fetch_report",
"type": "action",
"action": "api.request",
"config": {
"url": "https://api.example.com/v1/reports",
"method": "POST",
"headers": [{ "Key": "Authorization", "Value": "Bearer {{secrets.EXAMPLE_API_KEY}}" }],
"params": [{ "Key": "format", "Value": "detailed" }],
"body": { "startDate": "{{input.startDate}}", "endDate": "{{input.endDate}}" },
"responseFormat": "auto",
"retries": 3,
"retryDelayMs": 500
}
}
```
| Field | Type | Description |
|-------|------|-------------|
| `url` | string | Absolute https URL. Templates are resolved before the call. |
| `method` | string | `GET`, `POST`, `PUT`, `PATCH`, or `DELETE` (default `GET`) |
| `params` | json | Query parameters, as an object or a `[{Key, Value}]` table |
| `headers` | json | Request headers, same shapes. Use `{{secrets.NAME}}` for credentials. |
| `body` | json | Object (sent as JSON, sets `Content-Type`) or a raw string |
| `responseFormat` | string | `auto` (default), `json`, `csv`, `text`, `pdf`, or `binary` |
| `csvDelimiter` | string | Delimiter for `csv` parsing (default `,`) |
| `timeout` | number | Milliseconds; default 300000, capped at 600000 |
| `retries` | number | Retry attempts for timeouts, 408, 429 and 5xx (default 0) |
| `retryDelayMs` | number | Initial backoff, doubled each attempt (default 500) |
| `retryMaxDelayMs` | number | Backoff ceiling (default 30000) |
| `retryNonIdempotent` | boolean | Allow retries for `POST`/`PATCH` (default false) |
| `maxResponseBytes` | number | Refuse a larger response (default 20 MB) |
| `failOnError` | boolean | Throw on non-2xx (default true) |
Plain `http://` targets are rejected. The request is pinned to an address that was resolved and validated before the connection is opened, and an unencrypted hop cannot be trusted to reach that address — so the API block, like every outbound path on the platform, only speaks `https://`. Existing steps that name an `http://` URL fail at run time with `url must use https:// to a public destination.` until the URL is updated.
**Outputs:** `data` (parsed body), `status`, `headers`, `ok`, `contentType`, `sizeBytes`,
plus `text` for textual formats, `rows`/`columns` for CSV, and base64 `content` for
`pdf`/`binary` — so a downloaded file can flow straight into a `workspace_files`,
`data_table`, `transform`, or `agent` step.
`POST` and `PATCH` are **not** retried unless `retryNonIdempotent` is set, because a
retry can duplicate a side effect. Requests to loopback, private-network addresses and
cloud metadata endpoints are refused, and every redirect hop is re-checked before it is
followed.
## Template Variables
Use template syntax to reference input and previous step outputs:
```json
{
"id": "update-contact",
"type": "action",
"action": "hubspot.updateContact",
"config": {
"contactId": "{{steps.lookup.output.id}}",
"properties": {
"company": "{{input.company_name}}",
"lifecyclestage": "customer",
"last_order_date": "{{now}}"
}
}
}
```
### Available Template Contexts
| Context | Example | Description |
|---------|---------|-------------|
| `input` | `{{input.customer_id}}` | Workflow trigger input |
| `steps` | `{{steps.step-id.output.field}}` | Previous step output |
| `variables` | `{{variables.item}}` | Loop variables (the item and index a loop binds); empty outside a loop |
| `secrets` | `{{ secrets.API_TOKEN }}` | Workflow secrets, injected at dispatch |
| `now` | `{{now}}` | Current ISO timestamp |
### Nested Access
```json
{
"config": {
"email": "{{input.customer.contact.email}}",
"amount": "{{steps.calculate.output.totals.grandTotal}}"
}
}
```
## Error Handling
### Retry Configuration
Configure automatic retries for transient failures:
```json
{
"id": "api-call",
"type": "action",
"action": "stripe.createInvoice",
"config": { ... },
"retryConfig": {
"maxAttempts": 3,
"initialDelayMs": 1000,
"maxDelayMs": 30000,
"backoffMultiplier": 2
}
}
```
| Field | Type | Description |
|-------|------|-------------|
| `maxAttempts` | number | Maximum retry attempts (1-10) |
| `initialDelayMs` | number | Initial delay in ms (min: 100) |
| `maxDelayMs` | number | Maximum delay in ms (min: 1000) |
| `backoffMultiplier` | number | Exponential backoff multiplier (1-10) |
`retryConfig` is accepted by the step schema but is **not yet honoured by the
execution engine**, and `errorHandling.strategy: "retry"` re-raises to the task
runner rather than retrying the step. For real per-step retries today, use the
`api` block's own `retries` fields (above).
### Error Handling Strategy
```json
{
"id": "optional-sync",
"type": "action",
"action": "hubspot.updateContact",
"config": { ... },
"errorHandling": {
"strategy": "continue",
"fallback": {
"synced": false,
"error": "Sync failed"
}
}
}
```
| Strategy | Behavior |
|----------|----------|
| `fail` | Stop workflow, mark run as failed (default) |
| `continue` | Log error, continue with fallback output |
| `retry` | Retry with `retryConfig` settings |
### Timeout
```json
{
"id": "slow-api",
"type": "action",
"action": "netsuite.suiteql",
"config": { ... },
"timeoutMs": 60000
}
```
## Output
Action outputs are stored and available to subsequent steps:
```json
// Access in later steps
{{steps.create-invoice.output.id}}
{{steps.create-invoice.output.number}}
{{steps.create-invoice.output.status}}
{{steps.create-invoice.output.amount_due}}
```
### Checking Output Existence
```json
{
"id": "check-result",
"type": "condition",
"config": {
"conditions": {
"left": "{{steps.create-invoice.output.id}}",
"operator": "exists"
},
"then": ["send-notification"],
"else": ["handle-error"]
}
}
```
## Common Patterns
### Create Then Update
```json
{
"steps": [
{
"id": "create-customer",
"type": "action",
"action": "stripe.createCustomer",
"config": {
"email": "{{input.email}}",
"name": "{{input.name}}"
}
},
{
"id": "create-invoice",
"type": "action",
"action": "stripe.createInvoice",
"config": {
"customer": "{{steps.create-customer.output.id}}",
"auto_advance": true
}
}
]
}
```
### Conditional Action
```json
{
"steps": [
{
"id": "check-exists",
"type": "action",
"action": "hubspot.searchContacts",
"config": {
"filterGroups": [{
"filters": [{
"propertyName": "email",
"operator": "EQ",
"value": "{{input.email}}"
}]
}]
}
},
{
"id": "route-action",
"type": "condition",
"config": {
"conditions": {
"left": "{{steps.check-exists.output.total}}",
"operator": "gt",
"right": "0"
},
"then": ["update-contact"],
"else": ["create-contact"]
}
}
]
}
```
### With Fallback
```json
{
"id": "sync-to-crm",
"type": "action",
"action": "salesforce.updateAccount",
"config": {
"id": "{{input.sf_account_id}}",
"fields": { "Website": "{{input.website}}" }
},
"errorHandling": {
"strategy": "continue",
"fallback": {
"synced": false,
"syncError": "Failed to update Salesforce"
}
}
}
```
## Connector-Specific Examples
### Stripe
```json
{
"id": "create-payment",
"type": "action",
"action": "stripe.createPaymentIntent",
"config": {
"amount": "{{input.amount}}",
"currency": "usd",
"customer": "{{input.stripe_customer_id}}",
"metadata": {
"order_id": "{{input.order_id}}"
}
}
}
```
### Salesforce
```json
{
"id": "query-accounts",
"type": "action",
"action": "salesforce.query",
"config": {
"soql": "SELECT Id, Name, Website FROM Account WHERE Type = 'Customer' LIMIT 100"
}
}
```
### Slack
```json
{
"id": "notify-team",
"type": "action",
"action": "slack.sendMessage",
"config": {
"channel": "#sales-notifications",
"text": "New deal closed: {{input.deal_name}} for ${{input.amount}}"
}
}
```
## Troubleshooting
### Action Not Found
```json
{
"error": {
"code": "ACTION_NOT_FOUND",
"message": "Action 'stripe.unknownAction' not found"
}
}
```
Verify the action name matches the connector's available actions.
### Connection Required
```json
{
"error": {
"code": "CONNECTION_REQUIRED",
"message": "No active connection found for provider 'salesforce'"
}
}
```
Ensure you have an active OAuth connection for the connector.
### Rate Limited
```json
{
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded for provider"
}
}
```
Add retry configuration with exponential backoff.
## Next Steps
Add branching logic
Map and transform data
All connector actions
# Approval Steps (/docs/workflows/steps/approval)
Pause workflows for human approval or input
## Approval Steps
Approval steps enable human-in-the-loop (HITL) workflows by pausing execution until a designated approver takes action. Use them for scenarios requiring human judgment, data entry, or authorization before proceeding.
## Configuration
```json
{
"id": "manager-approval",
"type": "approval",
"name": "Request Manager Approval",
"config": {
"approvers": ["user@example.com"],
"reason": "Invoice #{{input.invoice_id}} for ${{input.amount}} requires approval",
"timeoutMs": 86400000,
"notifyChannels": [
{ "type": "slack", "channel": "C0123456789" },
{ "type": "email", "instructions": "Write a short email asking the approver to review the invoice." }
]
}
}
```
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Unique step identifier |
| `type` | string | Yes | Must be `"approval"` |
| `name` | string | Yes | Human-readable name |
| `config.approvers` | string[] | Yes | List of approver identifiers (email, user ID, or template). An entry that is one whole template resolving to a list, such as `["{{steps.build_approvers.result.approvers}}"]`, is flattened into the list. Entries are trimmed, blanks are dropped and duplicates are removed ignoring case, so at least one non-blank approver must remain. Any other entry (a number, an object, a list nested deeper) fails validation. `escalateTo` is normalized the same way. |
| `config.reason` | string | Yes | Reason shown to approvers explaining what needs approval |
| `config.timeoutMs` | number | No | Timeout in milliseconds (default: 86400000 / 24 hours) |
| `config.notifyChannels` | array | No | Where approval requests are sent: a list of Email and Slack destinations |
## Notification Channels
Configure where approval requests are sent. `notifyChannels` is a list; each entry is an Email or a Slack destination:
```json
{
"config": {
"notifyChannels": [
{ "type": "slack", "channel": "C0123456789" },
{ "type": "email", "instructions": "Write a short, polite email to a finance approver." }
]
}
}
```
| Entry | Field | Type | Description |
|-------|-------|------|-------------|
| Slack | `channel` | string | Slack channel ID (e.g. `C0123456789`). The approval request, with its Approve and Reject buttons, is posted here (see [Slack Requests](#slack-requests)). |
| Slack | `threadTs` | string | Optional. Thread timestamp to post into |
| Email | `instructions` | string | What the AI-written approval email should say. Required, but ignored when `bodyHtml` is set |
| Email | `sender` | string | Optional. From address |
| Email | `subject` | string | Optional. Fixed subject line, replacing the AI-written one (see [Fixed Email Body](#fixed-email-body)) |
| Email | `bodyHtml` | string | Optional. Email body built by the workflow, sent instead of an AI-written email (see [Fixed Email Body](#fixed-email-body)) |
### Fixed Email Body
By default the email body and subject are written by an AI model from the step's `reason`, `context` and `instructions`. To send the same email every time, build the HTML in an earlier step and pass it as `bodyHtml`. `subject` and `bodyHtml` are templates, resolved when the approval step runs:
```json
{
"config": {
"approveLabel": "Approve billing",
"rejectLabel": "Send back",
"notifyChannels": [
{
"type": "email",
"instructions": "Not used when bodyHtml is set.",
"subject": "Approve billing: {{steps.load_deal.name}}",
"bodyHtml": "{{steps.build_email.html}}"
}
]
}
}
```
- When `bodyHtml` resolves to text that is not blank, no AI model is called. `instructions` and `model` are ignored, but `instructions` must still be present.
- When `bodyHtml` is missing or blank, the email is written by the AI model as usual. `subject`, if set, still replaces the AI-written subject.
- Without `subject`, a fixed body is sent with the subject `Approval Required: `.
- When the request goes to the `escalateTo` approvers, a subject set by `subject` or by a fixed body starts with `Escalated: `. An AI-written subject is not changed.
- Line breaks and other control characters in `subject` are replaced with spaces, and it is cut to 200 characters.
- **Template values are inserted into `bodyHtml` as they are; they are not HTML-escaped.** If a value comes from outside your team (a CRM field, a customer name, an inbound email), escape `&`, `<` and `>` in it before it reaches `bodyHtml`, or it can change the email's markup. Tags outside the allowlist below are removed, but allowed tags in a value, including `https:` links, are kept and shown.
- The body is placed in the standard approval email, after the greeting and before the buttons and deadline, and goes through the same HTML allowlist as AI-written bodies. Allowed tags: `p`, `ul`, `ol`, `li`, `strong`, `em`, `a` (`https:` and `mailto:` links only), `br`, `table`, `thead`, `tbody`, `tfoot`, `tr`, `th`, `td`. Every other tag is removed and its text kept.
- On `th` and `td`, only `colspan` and `rowspan` (1 to 99) and `align` (`left`, `right`, `center`) are kept. All other attributes, including `style` and `class`, are removed; tables get a fixed border and padding.
- Tags are balanced before sending: a closing tag with nothing to close is removed, table rows and cells outside a table are removed (their text is kept), and anything left open is closed at the end of the body.
- A body longer than 200,000 characters is cut, any table the cut leaves open is closed, and a note after it says the full details are in the workflow run.
- Reminder, timeout and decision emails keep their standard text and do not use `bodyHtml` or `subject`. Reminder emails do show the step's `approveLabel` and `rejectLabel` on their buttons.
### Slack Requests
Each approver's request is posted in the Slack channel with its own Approve and Reject buttons.
- **Anyone in the channel can press them**, so manage who can decide through the channel's membership. Slack records who clicked.
- The post carries no **View approval** link, because that link works outside Slack.
- Broadcast and user-group mentions in the reason (``, ``, ``, ``) are shown as text.
- When the decision is made, the request is updated and its buttons are removed. Reminder replies in its thread keep theirs.
- If Slack refuses the post (for example, a private channel the Loopfour app has not been invited to), the request is sent to the approver as a Slack direct message, with a **View approval** link, and the channel gets a notice ("Approval requested for … Details sent privately to the approver.").
Requests go through the **first** Slack destination only. Every other Slack destination gets a short notice saying where the requests went.
### Slack Threading
Use `threadTs` to post the request into a thread. Reminders reply in the same thread:
```json
{
"id": "ask-for-input",
"type": "approval",
"config": {
"approvers": ["{{input.slackEvent.payload.event.user}}"],
"reason": "Please provide additional details",
"notifyChannels": [
{
"type": "slack",
"channel": "{{input.slackEvent.payload.event.channel}}",
"threadTs": "{{input.slackEvent.payload.event.ts}}"
}
]
}
}
```
Posting needs `chat:write`; posting to a public channel the Loopfour app has not joined also needs `chat:write.public`. Private channels and Slack Connect channels need the app invited. The direct-message fallback looks up the approver by email, so it also needs `users:read.email` and `im:write`. If the approver is not in the workspace or Slack rejects the DM, the worker sends the private approval link by email when an email provider is configured. Set `API_URL` on the Trigger.dev worker so the private **View approval** button opens the full reason and decision page.
## Slack Message After A Decision
When someone approves or rejects a request in Slack, the request message is updated: in the channel, or in the approver's DM when the request fell back to one. Two optional fields control what it becomes:
```json
{
"config": {
"decisionMessage": "keep_request",
"decisionMessageText": "Invoice {{steps.extract.invoice_number}} from {{steps.extract.vendor}}"
}
}
```
| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `decisionMessage` | string | `"replace"` | `"replace"` swaps the request for a short note: the decision, the workflow, and who decided. `"keep_request"` keeps the request as it was posted, removes the Approve and Reject buttons, and adds Approved or Rejected and who decided at the end. |
| `decisionMessageText` | string | - | Text added at the end of the updated message, in either mode. A fixed string or a template expression, resolved when the approval step runs, so it can show values from earlier steps. It must resolve to text; an expression that resolves to an object fails the step. Text over 3,000 characters is cut. |
Use `keep_request` when the request details should stay visible after the decision.
These settings apply when someone approves or rejects. A request that times out is still replaced with the timeout note.
Slack formatting in `decisionMessageText` is not escaped. Keep values that come from outside your company, such as an inbound email's sender or subject, out of it: text like `` or `` renders as a mention or a link.
## Input Types
Control how approvers interact with the approval request:
```json
{
"config": {
"inputType": "text",
"inputLabel": "Amount",
"inputPlaceholder": "Enter the invoice amount",
"approveLabel": "Submit",
"rejectLabel": "Cancel"
}
}
```
| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `inputType` | string | `"buttons"` | Input type: `"buttons"`, `"text"`, or `"both"` |
| `inputLabel` | string | - | Label for text input field |
| `inputPlaceholder` | string | - | Placeholder text for text input |
| `approveLabel` | string | `"Approve"` | Custom label for approve/submit button. Also used on the email and Slack request and reminder buttons, cut to 75 characters |
| `rejectLabel` | string | `"Reject"` | Custom label for reject/cancel button. Also used on the email and Slack request and reminder buttons, cut to 75 characters |
### Button Mode (Default)
Standard approve/reject buttons:
```json
{
"config": {
"inputType": "buttons",
"approveLabel": "Approve Request",
"rejectLabel": "Deny Request"
}
}
```
### Text Input Mode
Collect text input from approvers via a modal:
```json
{
"config": {
"inputType": "text",
"inputLabel": "Invoice Amount",
"inputPlaceholder": "Enter amount (e.g., 5000)",
"approveLabel": "Enter Input"
}
}
```
When `inputType` is `"text"`, clicking the approve button opens a Slack modal for text entry. The entered value is available in the step output.
### Both Mode
Show both approve/reject buttons and a text input option:
```json
{
"config": {
"inputType": "both",
"inputLabel": "Notes",
"inputPlaceholder": "Add optional notes",
"approveLabel": "Approve",
"rejectLabel": "Reject"
}
}
```
## Output
Approval steps return information about the decision:
```json
{
"decision": {
"approved": true,
"approvedBy": "user@example.com",
"approvedAt": "2024-01-15T10:30:00Z",
"reason": "Looks good, approved."
}
}
```
| Field | Description |
|-------|-------------|
| `decision.approved` | Whether the request was approved (`true`) or rejected (`false`) |
| `decision.approvedBy` | Identifier of the user who made the decision |
| `decision.approvedAt` | ISO 8601 timestamp of the decision |
| `decision.reason` | Text input provided by the approver (if `inputType` includes text) |
## Common Patterns
### Amount-Based Approval Routing
Route to different approvers based on amount:
```json
{
"steps": [
{
"id": "check-amount",
"type": "condition",
"config": {
"conditions": {
"left": "{{input.amount}}",
"operator": "gt",
"right": "10000"
},
"then": ["executive-approval"],
"else": ["manager-approval"]
}
},
{
"id": "executive-approval",
"type": "approval",
"config": {
"approvers": ["cfo@company.com"],
"reason": "High-value transaction: ${{input.amount}} requires executive approval",
"notifyChannels": {
"slack": "#executive-approvals",
"email": true
}
}
},
{
"id": "manager-approval",
"type": "approval",
"config": {
"approvers": ["{{input.manager_email}}"],
"reason": "Transaction of ${{input.amount}} requires manager approval",
"notifyChannels": {
"slack": "#manager-approvals",
"email": true
}
}
}
]
}
```
### Sequential Multi-Level Approval
Require approval from multiple levels:
```json
{
"steps": [
{
"id": "manager-approval",
"type": "approval",
"config": {
"approvers": ["{{input.manager}}"],
"reason": "Step 1/2: Manager approval for {{input.request_type}}",
"notifyChannels": { "slack": "#approvals" }
}
},
{
"id": "check-manager-decision",
"type": "condition",
"config": {
"conditions": {
"left": "{{steps.manager-approval.decision.approved}}",
"operator": "eq",
"right": "true"
},
"then": ["director-approval"],
"else": ["notify-rejection"]
}
},
{
"id": "director-approval",
"type": "approval",
"config": {
"approvers": ["{{input.director}}"],
"reason": "Step 2/2: Director approval for {{input.request_type}}",
"notifyChannels": { "slack": "#approvals" }
}
}
]
}
```
### Data Collection in Loops
Collect user input across multiple iterations:
```json
{
"steps": [
{
"id": "setup",
"type": "transform",
"config": {
"operation": "map",
"data": { "iterations": [1, 2, 3] }
}
},
{
"id": "collection-loop",
"type": "loop",
"config": {
"collection": "{{steps.setup.iterations}}",
"itemVariable": "iteration",
"steps": ["collect-value", "process-value"]
}
},
{
"id": "collect-value",
"type": "approval",
"config": {
"approvers": ["{{input.slackEvent.payload.event.user}}"],
"reason": "Iteration {{loop.iteration}}: Enter a value to process",
"inputType": "text",
"inputLabel": "Value",
"inputPlaceholder": "Enter a number",
"approveLabel": "Submit",
"notifyChannels": {
"slack": "{{input.slackEvent.payload.event.channel}}",
"slackThreadTs": "{{input.slackEvent.payload.event.ts}}"
}
}
},
{
"id": "process-value",
"type": "code",
"config": {
"action": "runCode",
"code": "return { value: parseFloat(input.userInput) || 0 };",
"input": {
"userInput": "{{steps.collect-value.decision.reason}}"
}
}
}
]
}
```
### Slack-Triggered Approval with Threading
Handle approvals from Slack conversations:
```json
{
"name": "Slack Approval Workflow",
"triggerConfig": {
"type": "slack_event",
"eventType": "message",
"channelTypes": ["channel"],
"keywords": ["request approval"]
},
"steps": [
{
"id": "acknowledge",
"type": "slack",
"config": {
"action": "send_message",
"channel": "{{input.slackEvent.payload.event.channel}}",
"text": "Processing your request...",
"thread_ts": "{{input.slackEvent.payload.event.ts}}"
}
},
{
"id": "get-approval",
"type": "approval",
"config": {
"approvers": ["manager@company.com"],
"reason": "Approval requested by <@{{input.slackEvent.payload.event.user}}>: {{input.slackEvent.payload.event.text}}",
"notifyChannels": {
"slack": "{{input.slackEvent.payload.event.channel}}",
"slackThreadTs": "{{input.slackEvent.payload.event.ts}}"
}
}
},
{
"id": "respond",
"type": "slack",
"config": {
"action": "send_message",
"channel": "{{input.slackEvent.payload.event.channel}}",
"text": "Your request was {{#if steps.get-approval.decision.approved}}approved{{else}}rejected{{/if}} by {{steps.get-approval.decision.approvedBy}}",
"thread_ts": "{{input.slackEvent.payload.event.ts}}"
}
}
]
}
```
## Timeout Handling
When an approval times out:
1. The step completes with a timeout status
2. The workflow can handle this in subsequent condition steps
```json
{
"steps": [
{
"id": "request-approval",
"type": "approval",
"config": {
"approvers": ["approver@company.com"],
"reason": "Urgent: Requires response within 1 hour",
"timeoutMs": 3600000
}
},
{
"id": "check-response",
"type": "condition",
"config": {
"conditions": {
"left": "{{steps.request-approval.decision.approved}}",
"operator": "exists"
},
"then": ["process-decision"],
"else": ["handle-timeout"]
}
}
]
}
```
## Best Practices
### Clear Approval Reasons
Provide context so approvers can make informed decisions:
```json
{
"reason": "Invoice #{{input.invoice_id}} from {{input.vendor_name}} for ${{input.amount}} (due: {{input.due_date}})"
}
```
### Appropriate Timeouts
Set timeouts based on urgency:
| Scenario | Timeout | Milliseconds |
|----------|---------|--------------|
| Urgent approval | 1 hour | `3600000` |
| Same-day approval | 8 hours | `28800000` |
| Standard approval | 24 hours | `86400000` |
| Extended review | 72 hours | `259200000` |
### Thread Continuity
For Slack-triggered workflows, maintain thread context:
```json
{
"notifyChannels": {
"slack": "{{input.slackEvent.payload.event.channel}}",
"slackThreadTs": "{{input.slackEvent.payload.event.ts}}"
}
}
```
## Troubleshooting
### Approval Not Received
1. **Check approvers list** - Ensure at least one valid approver is specified
2. **Verify channel access** - Bot must have access to notification channels
3. **Check timeout** - Approval may have expired
### Slack Modal Not Opening
1. **Verify inputType** - Must be `"text"` or `"both"` for modal
2. **Check connection** - Slack connection must be valid
3. **Ensure bot permissions** - Bot needs appropriate scopes
### Loop Iterations Not Waiting
Each iteration within a loop creates its own approval waitpoint. Ensure:
- Loop `concurrency` is set to `1` for sequential processing
- Each iteration waits for user response before continuing
## Next Steps
Timed delays and pauses
Branching based on approval decisions
Trigger workflows from Slack events
# Condition Steps (/docs/workflows/steps/conditions)
Branch workflows based on conditional logic
## Condition Steps
Condition steps enable branching logic in workflows, allowing you to execute different paths based on data values, comparisons, and complex boolean expressions.
## Configuration
```json
{
"id": "check-amount",
"type": "condition",
"name": "Check Invoice Amount",
"config": {
"conditions": {
"left": "{{input.amount}}",
"operator": "gt",
"right": "10000"
},
"then": ["high-value-flow"],
"else": ["standard-flow"]
}
}
```
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Unique step identifier |
| `type` | string | Yes | Must be `"condition"` |
| `name` | string | Yes | Human-readable name |
| `config.conditions` | object | Yes | Condition expression to evaluate |
| `config.then` | string[] | Yes | Step IDs to execute if true |
| `config.else` | string[] | No | Step IDs to execute if false |
## Simple Conditions
A simple condition compares two values using an operator:
```json
{
"config": {
"conditions": {
"left": "{{input.status}}",
"operator": "eq",
"right": "approved"
},
"then": ["process-order"],
"else": ["send-rejection"]
}
}
```
| Field | Description |
|-------|-------------|
| `left` | Left operand (template expression or literal) |
| `operator` | Comparison operator |
| `right` | Right operand (optional for some operators) |
## Comparison Operators
| Operator | Description | Example |
|----------|-------------|---------|
| `eq` | Equal to | `"status" eq "active"` |
| `ne` | Not equal to | `"type" ne "draft"` |
| `gt` | Greater than | `"amount" gt "1000"` |
| `gte` | Greater than or equal | `"count" gte "10"` |
| `lt` | Less than | `"priority" lt "5"` |
| `lte` | Less than or equal | `"score" lte "100"` |
| `contains` | String contains substring | `"email" contains "@company.com"` |
| `startsWith` | String starts with | `"id" startsWith "cus_"` |
| `endsWith` | String ends with | `"filename" endsWith ".pdf"` |
| `exists` | Value exists (not null/undefined) | `"customer_id" exists` |
| `isEmpty` | Value is empty | `"notes" isEmpty` |
| `matches` | Regex pattern match | `"phone" matches "^\+1"` |
### Operator Examples
**Numeric Comparison:**
```json
{
"conditions": {
"left": "{{input.order_total}}",
"operator": "gte",
"right": "100"
}
}
```
**String Comparison:**
```json
{
"conditions": {
"left": "{{input.email}}",
"operator": "endsWith",
"right": "@enterprise.com"
}
}
```
**Existence Check:**
```json
{
"conditions": {
"left": "{{input.coupon_code}}",
"operator": "exists"
}
}
```
**Regex Match:**
```json
{
"conditions": {
"left": "{{input.phone}}",
"operator": "matches",
"right": "^\\+1[0-9]{10}$"
}
}
```
## Compound Conditions
### AND Conditions
All conditions must be true:
```json
{
"config": {
"conditions": {
"operator": "and",
"conditions": [
{
"left": "{{input.status}}",
"operator": "eq",
"right": "active"
},
{
"left": "{{input.amount}}",
"operator": "gte",
"right": "1000"
}
]
},
"then": ["premium-processing"],
"else": ["standard-processing"]
}
}
```
### OR Conditions
At least one condition must be true:
```json
{
"config": {
"conditions": {
"operator": "or",
"conditions": [
{
"left": "{{input.priority}}",
"operator": "eq",
"right": "urgent"
},
{
"left": "{{input.vip}}",
"operator": "eq",
"right": "true"
}
]
},
"then": ["fast-track"],
"else": ["normal-queue"]
}
}
```
### NOT Conditions
Negate a condition:
```json
{
"config": {
"conditions": {
"not": {
"left": "{{input.status}}",
"operator": "eq",
"right": "cancelled"
}
},
"then": ["process"],
"else": ["skip"]
}
}
```
### Nested Conditions
Combine AND, OR, and NOT for complex logic:
```json
{
"config": {
"conditions": {
"operator": "and",
"conditions": [
{
"left": "{{input.status}}",
"operator": "eq",
"right": "active"
},
{
"operator": "or",
"conditions": [
{
"left": "{{input.amount}}",
"operator": "gt",
"right": "10000"
},
{
"left": "{{input.customer_tier}}",
"operator": "eq",
"right": "enterprise"
}
]
}
]
},
"then": ["priority-handling"],
"else": ["standard-handling"]
}
}
```
## Branching Patterns
### If/Else
Basic two-way branching:
```json
{
"id": "check-approval",
"type": "condition",
"config": {
"conditions": {
"left": "{{input.amount}}",
"operator": "gt",
"right": "5000"
},
"then": ["require-approval"],
"else": ["auto-approve"]
}
}
```
### Multiple Then Steps
Execute multiple steps when condition is true:
```json
{
"config": {
"conditions": {
"left": "{{input.new_customer}}",
"operator": "eq",
"right": "true"
},
"then": ["send-welcome-email", "create-onboarding-task", "notify-sales"],
"else": ["update-existing-record"]
}
}
```
### Chained Conditions (If/Else If/Else)
Use multiple condition steps for switch-like logic:
```json
{
"steps": [
{
"id": "check-tier-enterprise",
"type": "condition",
"config": {
"conditions": {
"left": "{{input.tier}}",
"operator": "eq",
"right": "enterprise"
},
"then": ["enterprise-flow"],
"else": ["check-tier-pro"]
}
},
{
"id": "check-tier-pro",
"type": "condition",
"config": {
"conditions": {
"left": "{{input.tier}}",
"operator": "eq",
"right": "pro"
},
"then": ["pro-flow"],
"else": ["free-flow"]
}
}
]
}
```
### Guard Conditions
Exit early if a condition isn't met:
```json
{
"steps": [
{
"id": "validate-input",
"type": "condition",
"config": {
"conditions": {
"left": "{{input.required_field}}",
"operator": "exists"
},
"then": ["continue-processing"],
"else": []
}
}
]
}
```
An empty `else: []` means the workflow ends without error if the condition is false.
## Using Step Outputs
Reference previous step outputs in conditions:
```json
{
"steps": [
{
"id": "fetch-customer",
"type": "action",
"action": "stripe.getCustomer",
"config": { "customerId": "{{input.customer_id}}" }
},
{
"id": "check-balance",
"type": "condition",
"config": {
"conditions": {
"left": "{{steps.fetch-customer.output.balance}}",
"operator": "gt",
"right": "0"
},
"then": ["send-balance-reminder"],
"else": ["send-thank-you"]
}
}
]
}
```
## Common Patterns
### Approval Routing
Route based on amount thresholds:
```json
{
"id": "route-approval",
"type": "condition",
"name": "Route by Amount",
"config": {
"conditions": {
"operator": "or",
"conditions": [
{
"left": "{{input.amount}}",
"operator": "gt",
"right": "50000"
},
{
"left": "{{input.risk_score}}",
"operator": "gt",
"right": "80"
}
]
},
"then": ["executive-approval"],
"else": ["manager-approval"]
}
}
```
### Feature Flags
Check for optional features:
```json
{
"id": "check-feature",
"type": "condition",
"config": {
"conditions": {
"left": "{{input.features.advanced_analytics}}",
"operator": "eq",
"right": "true"
},
"then": ["run-advanced-analytics"],
"else": ["run-basic-report"]
}
}
```
### Error Recovery
Check if a previous step succeeded:
```json
{
"id": "check-api-result",
"type": "condition",
"config": {
"conditions": {
"left": "{{steps.api-call.output.success}}",
"operator": "eq",
"right": "true"
},
"then": ["process-result"],
"else": ["handle-error", "notify-admin"]
}
}
```
### Data Validation
Validate required fields before processing:
```json
{
"id": "validate-order",
"type": "condition",
"name": "Validate Order Data",
"config": {
"conditions": {
"operator": "and",
"conditions": [
{ "left": "{{input.customer_id}}", "operator": "exists" },
{ "left": "{{input.items}}", "operator": "exists" },
{ "left": "{{input.items.length}}", "operator": "gt", "right": "0" }
]
},
"then": ["process-order"],
"else": ["reject-invalid-order"]
}
}
```
## Troubleshooting
### Condition Always False
1. **Check template syntax** - Ensure `{{}}` wrapping is correct
2. **Verify data types** - Numbers should be compared as numbers
3. **Check for null values** - Use `exists` operator first
4. **Debug with transform** - Add a transform step to log values
### Type Coercion
Values are compared as strings by default. For numeric comparisons, ensure both operands are numeric:
```json
// May not work as expected (string comparison)
{
"left": "{{input.count}}",
"operator": "gt",
"right": "9" // "10" < "9" as strings!
}
// Works correctly (treated as numbers)
{
"left": "{{input.count}}",
"operator": "gt",
"right": "9" // Template engine handles numeric comparison
}
```
### Missing Branches
If neither `then` nor `else` matches, the workflow continues to the next sequential step.
## Next Steps
Map and transform data
Iterate over collections
Execute steps concurrently
# Transform Steps (/docs/workflows/steps/transforms)
Map, normalize, and validate data in workflows
## Transform Steps
Transform steps manipulate and reshape data as it flows through your workflow. They support field mapping, data normalization, validation, and enrichment operations.
## Configuration
```json
{
"id": "transform-data",
"type": "transform",
"name": "Transform Customer Data",
"config": {
"action": "transform",
"sourceData": "{{input}}",
"targetSchema": {
"type": "object",
"properties": {
"fullName": { "type": "string" },
"email": { "type": "string" }
}
},
"mappingRules": [
{
"source": "first_name",
"target": "fullName",
"transform": "capitalize"
}
]
}
}
```
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Unique step identifier |
| `type` | string | Yes | Must be `"transform"` |
| `name` | string | Yes | Human-readable name |
| `config.action` | string | No | Transform action (default: `transform`) |
| `config.sourceData` | string | Yes | Template expression for source data |
| `config.targetSchema` | object | No | JSON Schema for target structure |
| `config.mappingRules` | array | No | Field mapping rules |
| `config.normalizations` | array | No | Data normalization rules |
| `config.validationRules` | array | No | Validation rules |
| `config.strict` | boolean | No | Fail on any transformation error |
## Transform Actions
| Action | Description |
|--------|-------------|
| `transform` | Full transformation with mapping and normalization |
| `map` | Simple field-to-field mapping |
| `normalize` | Standardize data formats |
| `validate` | Validate data against schema |
| `enrich` | Add computed or external data |
## Transform Types
Transforms can be categorized by type:
| Type | Description |
|------|-------------|
| `mapping` | Field-to-field transformations |
| `normalization` | Data standardization |
| `enrichment` | Adding external or computed data |
| `aggregation` | Combining multiple values |
| `custom` | Custom transformation logic |
## Mapping Rules
Mapping rules define how fields are transformed from source to target:
```json
{
"config": {
"action": "map",
"sourceData": "{{input}}",
"mappingRules": [
{
"source": "customer.firstName",
"target": "name.first",
"transform": "capitalize"
},
{
"source": "customer.lastName",
"target": "name.last",
"transform": "uppercase"
},
{
"source": "customer.emailAddress",
"target": "email",
"transform": "lowercase",
"required": true
}
]
}
}
```
### Mapping Rule Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | No | Unique rule identifier |
| `source` | string | Yes | JSONPath or dot notation to source field |
| `target` | string | Yes | JSONPath or dot notation to target field |
| `transform` | string | No | Transformation operation (default: `direct`) |
| `customTransform` | string | No | Natural language transformation description |
| `default` | any | No | Default value if source is missing |
| `required` | boolean | No | Whether source field is required |
| `condition` | string | No | Condition for applying this rule |
### Field Transforms
| Transform | Description | Example |
|-----------|-------------|---------|
| `direct` | Copy value as-is | `"John"` → `"John"` |
| `uppercase` | Convert to uppercase | `"John"` → `"JOHN"` |
| `lowercase` | Convert to lowercase | `"John"` → `"john"` |
| `trim` | Remove whitespace | `" John "` → `"John"` |
| `capitalize` | Capitalize first letter | `"john"` → `"John"` |
| `titlecase` | Title Case Each Word | `"john doe"` → `"John Doe"` |
| `snake_case` | Convert to snake_case | `"firstName"` → `"first_name"` |
| `camelCase` | Convert to camelCase | `"first_name"` → `"firstName"` |
| `number` | Parse as number | `"123"` → `123` |
| `string` | Convert to string | `123` → `"123"` |
| `boolean` | Parse as boolean | `"true"` → `true` |
| `array` | Wrap in array | `"value"` → `["value"]` |
| `flatten` | Flatten nested array | `[[1], [2]]` → `[1, 2]` |
| `custom` | Custom transformation | Use with `customTransform` |
### Conditional Mapping
Apply mappings conditionally:
```json
{
"mappingRules": [
{
"source": "amount",
"target": "total",
"transform": "number",
"condition": "{{input.currency}} === 'USD'"
},
{
"source": "amount_eur",
"target": "total",
"transform": "number",
"condition": "{{input.currency}} === 'EUR'"
}
]
}
```
### Default Values
Provide fallback values for missing fields:
```json
{
"mappingRules": [
{
"source": "customer.phone",
"target": "contactPhone",
"default": "Not provided"
},
{
"source": "preferences.language",
"target": "locale",
"default": "en-US"
}
]
}
```
## Normalization Rules
Normalization rules standardize data formats:
```json
{
"config": {
"action": "normalize",
"sourceData": "{{input}}",
"normalizations": [
{
"field": "created_date",
"type": "date",
"format": "YYYY-MM-DD"
},
{
"field": "amount",
"type": "currency",
"locale": "en-US"
},
{
"field": "phone_number",
"type": "phone",
"format": "E.164"
}
]
}
}
```
### Normalization Types
| Type | Description | Example |
|------|-------------|---------|
| `date` | Standardize date format | `"01/15/2024"` → `"2024-01-15"` |
| `currency` | Format currency values | `1234.5` → `"$1,234.50"` |
| `phone` | Standardize phone numbers | `"(555) 123-4567"` → `"+15551234567"` |
| `address` | Normalize address format | Standardize street, city, zip |
| `name` | Standardize name format | `"JOHN DOE"` → `"John Doe"` |
| `email` | Normalize email addresses | `"John@EXAMPLE.com"` → `"john@example.com"` |
| `url` | Standardize URLs | Add protocol, normalize case |
| `percentage` | Format percentages | `0.156` → `"15.6%"` |
### Normalization Rule Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | No | Unique rule identifier |
| `field` | string | Yes | Field path to normalize |
| `type` | string | Yes | Type of normalization |
| `format` | string | No | Target format (e.g., `YYYY-MM-DD` for dates) |
| `locale` | string | No | Locale for formatting (e.g., `en-US`) |
| `options` | object | No | Additional normalization options |
### Date Normalization Examples
```json
{
"normalizations": [
{
"field": "order_date",
"type": "date",
"format": "YYYY-MM-DD"
},
{
"field": "timestamp",
"type": "date",
"format": "ISO8601"
},
{
"field": "birth_date",
"type": "date",
"format": "MM/DD/YYYY",
"locale": "en-US"
}
]
}
```
### Currency Normalization Examples
```json
{
"normalizations": [
{
"field": "price",
"type": "currency",
"locale": "en-US",
"options": {
"currency": "USD",
"minimumFractionDigits": 2
}
},
{
"field": "total_eur",
"type": "currency",
"locale": "de-DE",
"options": {
"currency": "EUR"
}
}
]
}
```
## Validation Rules
Validate transformed data against constraints:
```json
{
"config": {
"action": "validate",
"sourceData": "{{steps.transform.output}}",
"validationRules": [
{
"field": "email",
"rule": "required",
"message": "Email is required"
},
{
"field": "email",
"rule": "pattern",
"value": "^[^@]+@[^@]+\\.[^@]+$",
"message": "Invalid email format"
},
{
"field": "age",
"rule": "range",
"value": { "min": 18, "max": 120 },
"message": "Age must be between 18 and 120"
}
]
}
}
```
### Validation Rule Types
| Rule | Description | Value Example |
|------|-------------|---------------|
| `required` | Field must exist and not be null | N/A |
| `type` | Field must be specific type | `"string"`, `"number"`, `"boolean"` |
| `pattern` | Field must match regex | `"^[A-Z]{2}$"` |
| `range` | Numeric range | `{ "min": 0, "max": 100 }` |
| `enum` | Must be one of listed values | `["active", "inactive", "pending"]` |
| `custom` | Custom validation expression | `"{{value}} > 0"` |
### Validation Rule Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | No | Unique rule identifier |
| `field` | string | Yes | Field path to validate |
| `rule` | string | Yes | Validation type |
| `value` | any | Depends | Validation parameter |
| `message` | string | No | Custom error message |
## Target Schema
Define the expected output structure:
```json
{
"config": {
"action": "transform",
"sourceData": "{{input}}",
"targetSchema": {
"type": "object",
"required": ["customerId", "email"],
"properties": {
"customerId": {
"type": "string",
"pattern": "^cus_[a-zA-Z0-9]+$"
},
"email": {
"type": "string",
"format": "email"
},
"name": {
"type": "object",
"properties": {
"first": { "type": "string" },
"last": { "type": "string" }
}
},
"tags": {
"type": "array",
"items": { "type": "string" }
}
}
},
"mappingRules": [...]
}
}
```
## Using Templates
Use pre-built transform templates:
```json
{
"config": {
"action": "transform",
"templateId": "stripe-to-quickbooks-customer",
"sourceData": "{{steps.get-customer.output}}"
}
}
```
## Transform Output
Transform steps output detailed reports:
```json
{
"transformed": {
"customerId": "cus_abc123",
"email": "customer@example.com",
"name": {
"first": "John",
"last": "Doe"
}
},
"mappingReport": {
"successful": ["customerId", "email", "name.first", "name.last"],
"failed": [],
"defaultsUsed": ["phone"],
"skipped": []
},
"normalizationReport": {
"normalized": ["email"],
"issues": []
},
"validationErrors": [],
"isValid": true,
"metadata": {
"sourceFieldCount": 5,
"targetFieldCount": 4,
"transformDurationMs": 12
}
}
```
### Output Fields
| Field | Description |
|-------|-------------|
| `transformed` | The transformed data matching target schema |
| `mappingReport` | Report of field mapping operations |
| `normalizationReport` | Report of normalization operations |
| `validationErrors` | List of validation errors |
| `isValid` | Whether the transformation is valid |
| `metadata` | Transformation statistics |
## Common Patterns
### Data Mapping Between Systems
Map Stripe customer to QuickBooks format:
```json
{
"id": "map-to-qb",
"type": "transform",
"name": "Map to QuickBooks",
"config": {
"action": "map",
"sourceData": "{{steps.stripe-customer.output}}",
"mappingRules": [
{
"source": "name",
"target": "DisplayName",
"transform": "titlecase"
},
{
"source": "email",
"target": "PrimaryEmailAddr.Address",
"transform": "lowercase"
},
{
"source": "phone",
"target": "PrimaryPhone.FreeFormNumber"
},
{
"source": "address.line1",
"target": "BillAddr.Line1"
},
{
"source": "address.city",
"target": "BillAddr.City"
},
{
"source": "address.state",
"target": "BillAddr.CountrySubDivisionCode",
"transform": "uppercase"
},
{
"source": "address.postal_code",
"target": "BillAddr.PostalCode"
}
]
}
}
```
### Data Cleanup and Standardization
```json
{
"id": "cleanup-data",
"type": "transform",
"name": "Clean Customer Data",
"config": {
"action": "normalize",
"sourceData": "{{input}}",
"normalizations": [
{
"field": "email",
"type": "email"
},
{
"field": "phone",
"type": "phone"
},
{
"field": "name",
"type": "name"
},
{
"field": "created_at",
"type": "date",
"format": "ISO8601"
}
]
}
}
```
### Validation Before API Call
```json
{
"id": "validate-invoice",
"type": "transform",
"name": "Validate Invoice Data",
"config": {
"action": "validate",
"sourceData": "{{input}}",
"validationRules": [
{
"field": "customer_id",
"rule": "required",
"message": "Customer ID is required"
},
{
"field": "customer_id",
"rule": "pattern",
"value": "^cus_",
"message": "Invalid customer ID format"
},
{
"field": "line_items",
"rule": "required",
"message": "At least one line item is required"
},
{
"field": "amount",
"rule": "range",
"value": { "min": 100 },
"message": "Amount must be at least $1.00"
}
],
"strict": true
}
}
```
### Enriching Data
Add computed fields:
```json
{
"id": "enrich-order",
"type": "transform",
"name": "Enrich Order Data",
"config": {
"action": "enrich",
"sourceData": "{{input}}",
"targetSchema": {
"type": "object",
"properties": {
"orderId": { "type": "string" },
"subtotal": { "type": "number" },
"tax": { "type": "number" },
"total": { "type": "number" },
"processedAt": { "type": "string" }
}
},
"mappingRules": [
{
"source": "id",
"target": "orderId"
},
{
"source": "amount",
"target": "subtotal",
"transform": "number"
}
],
"customInstructions": "Calculate tax at 8% and total. Add processedAt with current timestamp."
}
}
```
### Flattening Nested Data
```json
{
"id": "flatten-contacts",
"type": "transform",
"name": "Flatten Contact List",
"config": {
"action": "transform",
"sourceData": "{{steps.fetch-accounts.output.accounts}}",
"mappingRules": [
{
"source": "contacts",
"target": "allContacts",
"transform": "flatten"
}
]
}
}
```
## Strict Mode
Enable strict mode to fail on any transformation error:
```json
{
"config": {
"action": "transform",
"sourceData": "{{input}}",
"mappingRules": [...],
"strict": true
}
}
```
In strict mode:
- Missing required fields cause failure
- Transformation errors stop execution
- Validation errors cause failure
Without strict mode (default):
- Missing fields use defaults or are skipped
- Transformation errors are logged but continue
- Validation errors are reported but don't stop execution
## Troubleshooting
### Mapping Not Working
1. **Check field paths** - Use dot notation for nested fields
2. **Verify source data** - Add a debug transform to inspect data
3. **Check transform type** - Ensure correct transform for the data type
### Data Type Issues
1. **Use explicit transforms** - Add `number`, `string`, `boolean` transforms
2. **Check for null values** - Use `default` for missing fields
3. **Validate input** - Add validation step before transform
### Performance
1. **Minimize rules** - Combine mappings where possible
2. **Use templates** - Pre-built templates are optimized
3. **Skip unnecessary fields** - Only map fields you need
## Next Steps
Execute integration actions
Add branching logic
Pause workflow execution
# Wait Steps (/docs/workflows/steps/wait)
Pause workflow execution for timed delays
## Wait Steps
Wait steps pause workflow execution for a specified duration. They're useful for rate limiting, scheduling delays, and allowing external processes to complete.
## Configuration
```json
{
"id": "wait-before-retry",
"type": "wait",
"name": "Wait Before Retry",
"config": {
"duration": 5000
}
}
```
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Unique step identifier |
| `type` | string | Yes | Must be `"wait"` |
| `name` | string | Yes | Human-readable name |
| `config.duration` | number | Yes | Wait time in milliseconds |
## Duration
The `duration` field specifies how long to pause in milliseconds:
```json
{
"config": {
"duration": 30000
}
}
```
### Common Durations
| Duration | Milliseconds | Use Case |
|----------|--------------|----------|
| 1 second | `1000` | Quick pause |
| 5 seconds | `5000` | Brief delay |
| 30 seconds | `30000` | Rate limiting |
| 1 minute | `60000` | Processing time |
| 5 minutes | `300000` | External sync |
| 1 hour | `3600000` | Scheduled delay |
## Output
Wait steps return information about the wait:
```json
{
"waited": 5000
}
```
| Field | Description |
|-------|-------------|
| `waited` | The actual duration waited (in ms) |
## Common Patterns
### Rate Limiting
Add delays between API calls to avoid rate limits:
```json
{
"steps": [
{
"id": "first-api-call",
"type": "action",
"action": "hubspot.getContact",
"config": { "contactId": "{{input.contactId}}" }
},
{
"id": "rate-limit-delay",
"type": "wait",
"name": "Rate Limit Delay",
"config": {
"duration": 1000
}
},
{
"id": "second-api-call",
"type": "action",
"action": "hubspot.updateContact",
"config": {
"contactId": "{{input.contactId}}",
"properties": { ... }
}
}
]
}
```
### Retry with Delay
Wait before retrying a failed operation:
```json
{
"steps": [
{
"id": "attempt-sync",
"type": "action",
"action": "salesforce.updateAccount",
"config": { ... },
"errorHandling": {
"strategy": "continue",
"fallback": { "success": false }
}
},
{
"id": "check-success",
"type": "condition",
"config": {
"conditions": {
"left": "{{steps.attempt-sync.output.success}}",
"operator": "eq",
"right": "false"
},
"then": ["wait-and-retry"],
"else": ["continue-flow"]
}
},
{
"id": "wait-and-retry",
"type": "wait",
"name": "Wait Before Retry",
"config": {
"duration": 5000
}
},
{
"id": "retry-sync",
"type": "action",
"action": "salesforce.updateAccount",
"config": { ... }
}
]
}
```
### Processing Delay
Wait for external system to process:
```json
{
"steps": [
{
"id": "submit-document",
"type": "action",
"action": "pandadoc.sendDocument",
"config": {
"documentId": "{{input.documentId}}"
}
},
{
"id": "wait-for-processing",
"type": "wait",
"name": "Wait for Document Processing",
"config": {
"duration": 10000
}
},
{
"id": "check-status",
"type": "action",
"action": "pandadoc.getDocumentStatus",
"config": {
"documentId": "{{input.documentId}}"
}
}
]
}
```
### Scheduled Notification Delay
Delay a notification:
```json
{
"steps": [
{
"id": "create-invoice",
"type": "action",
"action": "stripe.createInvoice",
"config": { ... }
},
{
"id": "wait-before-reminder",
"type": "wait",
"name": "Wait 24 Hours",
"config": {
"duration": 86400000
}
},
{
"id": "send-reminder",
"type": "action",
"action": "slack.sendMessage",
"config": {
"channel": "#finance",
"text": "Invoice {{steps.create-invoice.output.id}} is still unpaid"
}
}
]
}
```
### Polling Pattern
Poll for status with delays:
```json
{
"steps": [
{
"id": "start-export",
"type": "action",
"action": "netsuite.createExport",
"config": { "type": "invoices" }
},
{
"id": "poll-status",
"type": "loop",
"config": {
"collection": [1, 2, 3, 4, 5],
"itemVariable": "attempt",
"steps": ["check-export", "wait-if-pending"]
}
},
{
"id": "check-export",
"type": "action",
"action": "netsuite.getExportStatus",
"config": {
"exportId": "{{steps.start-export.output.id}}"
}
},
{
"id": "wait-if-pending",
"type": "condition",
"config": {
"conditions": {
"left": "{{steps.check-export.output.status}}",
"operator": "eq",
"right": "pending"
},
"then": ["wait-poll"],
"else": []
}
},
{
"id": "wait-poll",
"type": "wait",
"name": "Poll Delay",
"config": {
"duration": 5000
}
}
]
}
```
## Dynamic Duration
Use template expressions for dynamic wait times:
```json
{
"id": "dynamic-wait",
"type": "wait",
"name": "Dynamic Delay",
"config": {
"duration": "{{input.delayMs}}"
}
}
```
Or calculate based on previous step output:
```json
{
"steps": [
{
"id": "get-retry-delay",
"type": "transform",
"config": {
"action": "map",
"sourceData": "{{input}}",
"mappingRules": [
{
"source": "retryCount",
"target": "delayMs",
"customTransform": "Multiply by 1000 for exponential backoff"
}
]
}
},
{
"id": "backoff-wait",
"type": "wait",
"name": "Exponential Backoff",
"config": {
"duration": "{{steps.get-retry-delay.output.delayMs}}"
}
}
]
}
```
## Best Practices
### Reasonable Timeouts
Keep wait durations reasonable for your use case:
- **API rate limiting**: 100-1000ms
- **Processing delays**: 5-30 seconds
- **Polling intervals**: 5-60 seconds
- **Scheduled delays**: Use schedule triggers instead for hours/days
### Avoid Long Waits
For delays longer than a few minutes, consider:
1. **Schedule triggers** - Use cron or interval triggers instead
2. **Subworkflows** - Split workflow at natural pause points
3. **External scheduling** - Let external systems handle timing
### Idempotency
Design steps after waits to be idempotent in case of restarts:
```json
{
"steps": [
{
"id": "wait-for-sync",
"type": "wait",
"config": { "duration": 60000 }
},
{
"id": "check-already-processed",
"type": "condition",
"config": {
"conditions": {
"left": "{{steps.lookup.output.processed}}",
"operator": "eq",
"right": "true"
},
"then": [],
"else": ["do-processing"]
}
}
]
}
```
## Troubleshooting
### Wait Not Working
1. **Check duration type** - Must be a number in milliseconds
2. **Verify template resolution** - Dynamic values must resolve to numbers
3. **Check workflow status** - Workflow must be active
### Workflow Timeout
If your total wait time exceeds the workflow timeout:
1. **Split into subworkflows** - Break at natural boundaries
2. **Use schedule triggers** - For long delays
3. **Reduce polling frequency** - Increase wait duration between checks
### Resource Usage
Long-running waits consume resources:
1. **Use appropriate intervals** - Don't poll too frequently
2. **Consider schedules** - For regular intervals
3. **Monitor run duration** - Track total workflow time
## Next Steps
Execute integration actions
Add branching logic
Map and transform data