n8n Integration

LostChurn integrates with n8n, the open-source workflow automation platform. Use n8n to build custom recovery workflows, sync data to internal systems, or trigger notifications — all on your own infrastructure.

Prerequisites

• An n8n instance (self-hosted or n8n Cloud)
• A LostChurn account with an API key (generate one at Settings > API Keys)

Connection Methods

There are two ways to connect LostChurn to n8n:

Option A: Webhook Trigger (No Install Required)

The simplest approach uses n8n's built-in Webhook node to receive LostChurn outbound webhook events directly. No custom node installation is needed.

1. In n8n, create a new workflow.
2. Add a Webhook node as the trigger.
3. Set the HTTP method to POST.
4. Copy the webhook URL (it looks like https://your-n8n.example.com/webhook/abc-123).
5. In your LostChurn dashboard, go to Settings > Webhooks.
6. Click Add Endpoint and paste the n8n webhook URL.
7. Select the event types you want to receive (e.g., recovery.succeeded, payment.failed).
8. Click Create.
9. Back in n8n, click Listen for Test Event, then click Send Test Event in LostChurn.
10. The test payload appears in n8n. Build your workflow from there.

Option B: LostChurn Community Node

For a richer experience with built-in triggers, actions, and credential management, install the LostChurn community node.

Installation

n8n Cloud:

1. Go to Settings > Community Nodes.
2. Search for @lostchurn/n8n-nodes.
3. Click Install.

Self-hosted:

cd ~/.n8n
npm install @lostchurn/n8n-nodes

Restart your n8n instance after installation.

Authentication

1. In n8n, go to Credentials > New Credential.
2. Search for LostChurn API.
3. Enter your LostChurn API key.
4. Click Save.

Available Trigger Events

Whether you use the Webhook node or the community node, LostChurn sends the same event payloads:

Available Actions (Community Node)

The LostChurn community node provides these action nodes:

Example Workflows

Recovery Alert to Slack

[LostChurn Trigger: recovery.succeeded]
    → [Slack: Send Message]
        Channel: #revenue-recovered
        Message: "Recovered ${{$json.amount / 100}} from {{$json.customer_email}}"

Failed Payment to Database

[LostChurn Trigger: payment.failed]
    → [Postgres: Insert Row]
        Table: failed_payments
        Columns: email, amount, decline_code, timestamp

Recovery Exhausted to Manual Review

[LostChurn Trigger: recovery.exhausted]
    → [IF: amount > 10000]
        → True: [Gmail: Send Email] to cs-team@company.com
        → False: [Google Sheets: Append Row] for monthly review

Multi-Step CRM Sync

[LostChurn Trigger: recovery.succeeded]
    → [HTTP Request: GET HubSpot Contact by email]
    → [IF: Contact exists]
        → True: [HTTP Request: UPDATE HubSpot Contact]
        → False: [HTTP Request: CREATE HubSpot Contact]
    → [HTTP Request: CREATE HubSpot Deal]

Webhook Payload Format

All events follow the same structure documented in Outbound Webhooks:

{
  "id": "evt_abc123",
  "type": "recovery.succeeded",
  "created_at": "2026-03-13T10:30:00Z",
  "data": {
    "recovery_id": "rec_xyz789",
    "customer_email": "jane@example.com",
    "customer_name": "Jane Doe",
    "amount": 4999,
    "currency": "usd",
    "decline_code": "insufficient_funds",
    "retry_count": 2,
    "recovered_at": "2026-03-13T10:30:00Z"
  }
}

Signature Verification

LostChurn signs all outbound webhook payloads with HMAC-SHA256. To verify signatures in n8n:

1. Add a Code node after your Webhook trigger.
2. Use the following JavaScript to verify the signature:

const crypto = require('crypto');

const secret = 'your_webhook_signing_secret'; // from Settings > Webhooks
const signature = $input.first().headers['x-lostchurn-signature'];
const timestamp = $input.first().headers['x-lostchurn-timestamp'];
const body = JSON.stringify($input.first().json);

const expected = crypto
  .createHmac('sha256', secret)
  .update(`${timestamp}.${body}`)
  .digest('hex');

if (signature !== expected) {
  throw new Error('Invalid webhook signature');
}

return $input.all();

Rate Limits

When using the community node's action nodes, standard LostChurn API rate limits apply:

Webhook triggers are not rate-limited — events are delivered as they occur.

Troubleshooting

Webhook not receiving events

• Verify your n8n webhook URL is publicly accessible (not localhost)
• Check that the workflow is active (not in draft/test mode)
• Verify the webhook endpoint is active in Settings > Webhooks
• Check the delivery log in Settings > Webhooks > [endpoint] > Deliveries

Community node not appearing

• Ensure you restarted n8n after installing the package
• Check the n8n logs for installation errors
• Verify the package is installed: npm list @lostchurn/n8n-nodes

Authentication failed

• Generate a new API key at Settings > API Keys
• Update the credential in n8n at Credentials > LostChurn API
• Ensure the API key has the required scopes (webhooks:read, webhooks:write, recoveries:read)

Next Steps

• Zapier Integration — managed alternative to n8n
• Outbound Webhooks — full webhook API reference
• API Keys — manage API keys and scopes