Skip to content

V4 - TwilioStatusCallback

This workflow receives Twilio message status callbacks and updates delivery tracking in the database, providing real-time visibility into SMS message delivery states for the youth entrepreneur onboarding process.

Purpose

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

This workflow serves as a critical component for tracking SMS delivery status in the Sifa V4 system. It receives status updates from Twilio when messages are sent, delivered, read, or fail, and updates both the message log and youth entrepreneur records accordingly. This enables the system to track onboarding progress and identify delivery issues that might prevent participants from receiving important communications.

How It Works

  1. Webhook Reception: Twilio sends POST requests to the /webhook/twilio-status endpoint whenever a message status changes
  2. Data Parsing: The workflow extracts the Message SID, status, and any error codes from the Twilio callback payload
  3. Validation: Checks if a valid Message SID is present in the callback
  4. Message Log Update: Updates the v4_message_log table with the new status and timestamps for delivery events
  5. Entrepreneur Status Update: Updates the v4_youthEntrepreneurs table to reflect the onboarding message status

Workflow Diagram

graph TD
    A[Webhook: Twilio Status] --> B[Parse: Extract SID & Status]
    B --> C{IF has SID: Valid Message ID?}
    C -->|Yes| D[UpdateMessageLog: Update v4_message_log]
    C -->|No| E[End: Skip Processing]
    D --> F[UpdateStatus: Update v4_youthEntrepreneurs]
    F --> G[End: Status Updated]

Trigger

Webhook Trigger: Listens for POST requests at /webhook/twilio-status - Activated when Twilio sends status callback notifications - Expects Twilio's standard callback payload format

Nodes Used

Node Type Node Name Purpose
Webhook Webhook Receives POST requests from Twilio with message status updates
Code Parse Extracts MessageSid, MessageStatus, and ErrorCode from the callback payload
IF IF has SID Validates that a Message SID is present before processing
Postgres UpdateMessageLog Updates the v4_message_log table with status and timestamps
Postgres UpdateStatus Updates the v4_youthEntrepreneurs onboarding status
Sticky Note Note Documentation within the workflow

External Services & Credentials Required

Twilio: - Must configure this webhook URL as the StatusCallback in Twilio message sending - No Twilio credentials needed (receives callbacks only)

PostgreSQL Database: - Credential: sifaV4Dev - Requires read/write access to: - v4_message_log table - v4_youthEntrepreneurs table

Environment Variables

No environment variables are directly used in this workflow. Database connection details are managed through n8n credentials.

Data Flow

Input (Twilio Callback): 

1
2
3
4
5
{
  "MessageSid": "SM1234567890abcdef",
  "MessageStatus": "delivered",
  "ErrorCode": "30008"
}

Processing: - Extracts SID, status, and error code - Creates statusFull field combining status and error code (e.g., "failed #30008")

Output: - Updates v4_message_log with status, error_code, and appropriate timestamps - Updates v4_youthEntrepreneurs.onboarding_init_status where SID matches

Error Handling

  • Missing SID: If no MessageSid is present, the workflow stops processing (IF condition fails)
  • Database Errors: Both PostgreSQL nodes have "Always Output Data" enabled to continue execution even if updates fail
  • Invalid Payloads: The Parse node safely handles missing fields by defaulting to empty strings

Known Limitations

  • Currently only updates onboarding_init_status field - not extensible to other message types without modification
  • No retry mechanism for failed database updates
  • Assumes Twilio's standard callback format - custom fields may be ignored

This workflow is designed to work with other SMS sending workflows in the Sifa V4 system that set the StatusCallback URL to this endpoint.

Setup Instructions

  1. Import Workflow: Import the JSON into your n8n instance
  2. Configure Database Credential:
    • Create a PostgreSQL credential named sifaV4Dev
    • Ensure it has access to the required tables
  3. Database Schema: Ensure these tables exist with required columns: 
    1
2
3
4
5
    -- v4_message_log table needs:
-- message_sid, status, error_code, delivered_at, read_at, failed_at, updated_at

-- v4_youthEntrepreneurs table needs:
-- onboarding_init_sid, onboarding_init_status
  4. Activate Workflow: Enable the workflow to start receiving webhooks
  5. Configure Twilio: Set the StatusCallback URL in your Twilio messaging configuration to: https://your-n8n-instance.com/webhook/twilio-status
  6. Test: Send a test message through Twilio and verify status updates appear in the database