Skip to content

V4 - OnboardingInitiator

This workflow provides a secure API endpoint for external applications to initiate the onboarding process for youth entrepreneurs. When triggered with a phone number, it validates the user's eligibility, sends a personalized WhatsApp welcome message using an approved template, and updates the database to track the onboarding journey.

Purpose

No business context provided yet — add a context.md to enrich this documentation.

Based on the workflow implementation, this system appears to serve youth entrepreneurship programs by: - Enabling external applications to programmatically start onboarding flows - Ensuring only eligible participants receive onboarding messages - Preventing duplicate onboarding attempts for users already in progress - Maintaining comprehensive audit trails of all onboarding communications

How It Works

  1. Request Validation: External application sends POST request with phone number and authentication token
  2. Security Check: Validates the provided authentication token against expected secret
  3. Phone Format: Normalizes phone number to E.164 format (e.g., +254712345678)
  4. Database Lookup: Checks if the phone number exists in the youth entrepreneurs database
  5. Eligibility Assessment: Determines if user is eligible for onboarding (status must be 'new', not already in journey)
  6. WhatsApp Message: Sends personalized welcome template via Twilio WhatsApp API
  7. Database Update: Records onboarding initiation details and updates user status to first step
  8. Activity Logging: Creates chat log entry and message log for tracking
  9. Response: Returns appropriate status code and details to calling application

Workflow Diagram

graph TD
    A[Webhook] --> B[Validate]
    B --> C{IF ok?}
    C -->|Valid| D[Lookup]
    C -->|Invalid| E[Respond BadAuth]
    D --> F[Classify]
    F --> G{IF eligible?}
    G -->|Eligible| H[SendTemplate]
    G -->|Not Eligible| I[Respond NotEligible]
    H --> J[BuildResult]
    J --> K{IF accepted?}
    K -->|Success| L[UpdateDB]
    K -->|Failed| M[Respond SendFailed]
    L --> N[LogChat]
    N --> O[Respond Started]
    O --> P[LogMessage]

Trigger

Webhook: POST request to /onboarding-initiate endpoint - Method: POST - Authentication: Required via X-SIFA-Token header - Payload: JSON with phoneNumber and optional firstName

Nodes Used

Node Type Node Name Purpose
Webhook Webhook Receives POST requests from external applications
Code Validate Validates authentication token and phone number format
If IF ok? Routes based on validation success
Postgres Lookup Queries user data from youth entrepreneurs table
Code Classify Determines user eligibility for onboarding
If IF eligible? Routes based on eligibility status
HTTP Request SendTemplate Sends WhatsApp message via Twilio API
Code BuildResult Processes Twilio response and formats result
If IF accepted? Routes based on message send success
Postgres UpdateDB Updates user onboarding status and tracking fields
Postgres LogChat Creates chat log entry for audit trail
Respond to Webhook Respond Started Returns success response to caller
Respond to Webhook Respond BadAuth Returns authentication error
Respond to Webhook Respond NotEligible Returns eligibility error
Respond to Webhook Respond SendFailed Returns message send failure
Execute Workflow LogMessage Calls message logging workflow

External Services & Credentials Required

Twilio WhatsApp API

  • Service: Twilio Messaging API
  • Credential: HTTP Basic Auth (httpBasicAuth)
  • Purpose: Send WhatsApp template messages
  • Template: HXcd2b5373580fa8551be6ee863227e75e (sifa_onboarding_welcome)
  • From Number: whatsapp:+254203893815

PostgreSQL Database

  • Service: PostgreSQL database
  • Credential: sifaV4Dev postgres connection
  • Tables Used:
    • v4_youthEntrepreneurs (user data and onboarding status)
    • v4_chatLog (communication audit trail)

Message Logger Workflow

  • Service: Internal n8n workflow
  • Workflow ID: Ql5e1pI5nAGqsJFx
  • Purpose: Centralized message logging and analytics

Environment Variables

The workflow uses hardcoded values that should be externalized:

  • Authentication Token: sifa_onb_VvRCTN8b6PabR-qs1kUBWR4IFBirMJ1Q
  • Twilio Account SID: AC906ca9524b640bdad7d029fd565b6a02
  • WhatsApp Template SID: HXcd2b5373580fa8551be6ee863227e75e
  • Status Callback URL: https://experienceeducate.app.n8n.cloud/webhook/twilio-status

Data Flow

Input

1
2
3
4
{
  "phoneNumber": "+254712345678",
  "firstName": "John"
}

Headers Required

1
X-SIFA-Token: sifa_onb_VvRCTN8b6PabR-qs1kUBWR4IFBirMJ1Q

Successful Response (200)

1
2
3
4
5
6
{
  "status": "onboarding_started",
  "phoneNumber": "+254712345678",
  "messageSid": "SM...",
  "twilioStatus": "queued"
}

Error Responses

  • 401 Unauthorized: Invalid or missing authentication token
  • 400 Bad Request: Invalid phone number format
  • 404 Not Found: Phone number not found in database
  • 200 Already Started: User already in onboarding journey
  • 422 Send Failed: WhatsApp message delivery failed

Error Handling

The workflow implements comprehensive error handling:

  1. Authentication Failures: Returns 401 with unauthorized status
  2. Validation Errors: Returns 400 for malformed phone numbers
  3. User Not Found: Returns 404 when phone number doesn't exist in database
  4. Already Onboarding: Returns 200 with already_started status to prevent duplicates
  5. Message Send Failures: Returns 422 with Twilio error details
  6. Graceful Degradation: Uses neverError option on Twilio calls to handle API failures

Known Limitations

Based on the workflow notes, the following items are pending: 1. WhatsApp template requires Meta approval before production use 2. Database migration needed to add tracking fields: onboarding_init_sid, onboarding_init_status, onboarding_initiated_at 3. Status callback handling (Phase 2 / REG-09) not yet implemented 4. Authentication token is hardcoded and should be externalized

  • V4 - MessageLogger (Ql5e1pI5nAGqsJFx): Centralized logging for all message activities

Setup Instructions

  1. Import Workflow: Import the JSON into your n8n instance

  2. Configure Database Credential:

    • Create PostgreSQL credential named sifaV4Dev
    • Ensure access to v4_youthEntrepreneurs and v4_chatLog tables

  3. Configure Twilio Credential:

    • Create HTTP Basic Auth credential named Waringa twilio auth
    • Use Twilio Account SID as username and Auth Token as password

  4. Database Schema Requirements: 

    1
2
3
4
5
    -- Add these columns to v4_youthEntrepreneurs if not present
ALTER TABLE v4_youthEntrepreneurs 
ADD COLUMN onboarding_init_sid VARCHAR(255),
ADD COLUMN onboarding_init_status VARCHAR(50),
ADD COLUMN onboarding_initiated_at TIMESTAMP;

  5. WhatsApp Template Setup:

    • Ensure template HXcd2b5373580fa8551be6ee863227e75e is approved by Meta
    • Verify template content includes placeholder for first name

  6. Security Configuration:

    • Change the hardcoded authentication token
    • Update all references to the new token value
    • Consider using environment variables for sensitive values

  7. Test the Endpoint: 

    1
2
3
4
    curl -X POST https://your-n8n-instance/webhook/onboarding-initiate \
  -H "X-SIFA-Token: your-token-here" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber": "+254712345678", "firstName": "Test"}'

  8. Activate Workflow: Enable the workflow to start accepting requests