Skip to content

n8n Triggers

This document describes how to receive WhiteLabelCRO events in n8n workflows.

How Triggers Work

In n8n, you can receive WhiteLabelCRO events using two approaches:

For real-time event delivery: 1. Use n8n's Webhook node as the workflow trigger 2. Create a webhook subscription pointing to the n8n webhook URL via POST /api/v1/webhooks/subscriptions 3. When events occur in WhiteLabelCRO, they are pushed to n8n immediately 4. Your workflow processes each event as it arrives

Polling Approach

For periodic event retrieval: 1. Use n8n's Schedule Trigger node (e.g., every 5 minutes) 2. Add HTTP Request node to poll GET /api/v1/events 3. Use cursor-based pagination to track last retrieved event 4. Process new events in subsequent workflow nodes

Available Event Types (10)

Client Events

client.created - Fires when a new client is enrolled in the system - Key fields: client_id, first_name, last_name, email, phone, status, created_date

client.status_changed - Fires when a client moves to a different lifecycle stage - Key fields: client_id, previous_status, new_status, changed_date

lead.created - Fires when a new lead is captured - Key fields: client_id, first_name, last_name, email, phone, status, created_date

Billing Events

invoice.created - Fires when a new invoice is generated - Key fields: invoice_id, client_id, amount, due_date, description, invoice_status

invoice.status_changed - Fires when invoice payment status changes (Unpaid to Paid, etc.) - Key fields: invoice_id, previous_status, new_status, total_paid, balance

payment.succeeded - Fires when a payment processes successfully - Key fields: payment_id, invoice_id, client_id, payment_amount, payment_method, date_paid

payment.failed - Fires when a payment attempt is declined - Key fields: payment_id, invoice_id, client_id, amount_attempted, failure_reason

Partner Events

affiliate.created - Fires when a new referral partner is added - Key fields: employee_id, full_name, email, phone, is_approved_affiliate, created_date

Document Events

document.uploaded - Fires when a file is added to a client record - Key fields: client_doc_id, client_id, doc_name, doc_type_name, created_date

Compliance Events

agreement.signed - Fires when a client electronically signs a document - Key fields: agreement_signed_id, client_id, signed_date, name_signed, agreement_name

Setting Up Webhook Triggers

Step 1: Configure Webhook Node

  1. In n8n, create a new workflow
  2. Add a Webhook node as the trigger
  3. Set HTTP Method: POST
  4. Set Path: (e.g., /wlcro/events)
  5. Note the webhook URL (e.g., https://your-n8n.com/webhook/wlcro/events)

Step 2: Create Webhook Subscription

Using HTTP Request or external tool, call:

POST /api/v1/webhooks/subscriptions

Request body: 

{
  "url": "https://your-n8n.com/webhook/wlcro/events",
  "eventTypes": ["client.created", "payment.succeeded"],
  "enabled": true
}

See /04-api-reference/webhooks-api.md for complete subscription API details.

Add signature verification to your webhook workflow:

  1. Extract X-Webhook-Timestamp and X-Webhook-Signature headers
  2. Compute HMAC-SHA256 using signing secret (from subscription creation)
  3. Reject requests with invalid signatures

See /02-admin/webhook-subscriptions-and-security.md for verification implementation.

Setting Up Polling Triggers

Step 1: Add Schedule Trigger

  1. In n8n, create a new workflow
  2. Add Schedule Trigger node
  3. Set interval (e.g., every 5 minutes)

Step 2: Poll Events API

  1. Add HTTP Request node
  2. Set method: GET
  3. Set URL: https://your-api-url.com/api/v1/events
  4. Add query parameters:
  5. limit: 100 (max events per request)
  6. cursor: Use stored value from previous execution
  7. type: (optional) Filter by event type
  8. Configure authentication with your API key credential

Step 3: Track Cursor

  1. Store the nextCursor value from the response
  2. Use it in the next polling cycle
  3. Use n8n's workflow data storage or external database

See /04-api-reference/events-api.md for cursor-based pagination details.

Event Structure

Each event includes:

{
  "id": 12345,
  "type": "client.created",
  "createdUtc": "2026-01-28T10:30:00Z",
  "companyId": 92,
  "payload": {
    "client_id": 5678,
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com"
  },
  "metadata": {
    "source": "web_portal",
    "user_id": 42
  }
}

Access fields in n8n: - Event ID: {{ $json.id }} - Event type: {{ $json.type }} - Client ID: {{ $json.payload.client_id }} - Client name: {{ $json.payload.first_name }}

Processing Events

Filtering by Event Type

Use n8n's IF or Switch node to route based on event type:

{{ $json.type === 'client.created' }}

Accessing Nested Data

Use dot notation in expressions:

{{ $json.payload.email }}
{{ $json.metadata.source }}

Handling Missing Fields

Some optional fields may be null. Use default values:

{{ $json.payload.phone || 'No phone' }}

Deduplication

For Webhook Triggers

Events may be delivered multiple times due to retries. Deduplicate using the event id: 1. Store processed event IDs in a database or file 2. Check if $json.id exists before processing 3. Skip if already processed

For Polling Triggers

Cursor-based pagination ensures each event is retrieved once, but you may still want to track processed IDs for safety.

Troubleshooting

Webhooks Not Arriving

  1. Verify n8n webhook URL is publicly accessible (not localhost)
  2. Check webhook subscription is enabled in WhiteLabelCRO
  3. Verify event types match what you're expecting
  4. Check WhiteLabelCRO Admin Portal for delivery logs
  5. Test subscription using /api/v1/webhooks/subscriptions/{id}/test

Signature Verification Failing

  1. Using correct signing secret (from subscription creation)
  2. Computing HMAC over "{timestamp}.{raw_body}" (exact format)
  3. Not parsing request body before verification

Polling Returns No Events

  1. Confirm events are actually occurring in WhiteLabelCRO
  2. Check cursor value is correct
  3. Remove type filter to see all events
  4. Verify API key has events:read scope

Rate Limits Hit

Polling too frequently can hit rate limits: - Read bucket: 60 requests/minute - Reduce polling frequency (e.g., every 60 seconds minimum) - Implement exponential backoff on 429 errors

Platform Compatibility

The same events are available via: - Zapier - Using REST Hooks pattern - Make - Using HTTP modules - Custom code - Direct API calls

All platforms receive identical event structures and field names.