8x8 Inbound SMS Webhook Service

One-Line Summary: A lightweight Node.js webhook server that receives inbound SMS from 8x8 Connect/CPaaS, detects HELP/STOP/JOIN keywords, sends compliant auto-replies, and maintains a local opt-out store for carrier compliance.

--

Problem Statement

a subsidiary brand operates business SMS communications through the 8x8 platform on a registered toll-free number. Carrier compliance for A2P messaging requires that when a recipient texts specific keywords to a business number, the system must automatically reply with approved templates:

• STOP. Must immediately unsubscribe the sender and confirm opt-out
• HELP. Must provide contact information and support details
• JOIN. Must opt the sender back in and confirm enrollment

The 8x8 Work admin console does not support automatic keyword-based replies natively. This functionality requires 8x8 Connect/CPaaS access with webhook configuration and API integration. A compliance audit found that the campaign was failing because keyword testing (texting STOP/HELP/JOIN to the number) did not produce any responses, and the website originally lacked a proper express consent checkbox.

Without automated keyword handling, the brand cannot pass carrier compliance review, which blocks the entire A2P 10DLC campaign registration.

--

Solution

Built a standalone webhook service in vanilla Node.js (zero framework dependencies) that implements the complete SMS keyword handling pipeline:

Inbound Webhook Receiver

• Listens for POST requests from 8x8 on a configurable webhook path (/webhooks/8x8/inbound-sms)
• Validates the webhook payload structure (must be namespace: "SMS", eventType: "inbound_message_received")
• Supports optional Bearer token authentication for webhook security
• Normalizes the inbound payload to extract source number, destination number, and message body

Keyword Detection Engine

• Extracts the message body and normalizes to uppercase
• Matches against three supported keywords: HELP, STOP, JOIN
• Non-keyword messages are acknowledged but ignored (no auto-reply for regular messages)

Auto-Reply System

• STOP: Adds the sender to the local opt-out store, sends the unsubscribe confirmation via 8x8 Send SMS API
• JOIN: Removes the sender from the opt-out store, sends the opt-in confirmation
• HELP: Sends support information (email, phone number, data rates disclosure)
• All reply messages are configurable via environment variables
• Replies are sent through the 8x8 SMS API (/api/v1/subaccounts/{id}/messages) with Bearer token authentication

Opt-Out Store

• Maintains a persistent local store tracking all opted-out phone numbers
• STOP adds a number to the store; JOIN removes it
• Numbers in the opt-out store should be filtered from all future outbound messaging
• Phone numbers are normalized (stripped of non-digit characters except +) before storage

Health Check Endpoint

• GET /health returns the service status, webhook path, and current count of opted-out numbers
• Useful for monitoring and deployment verification

Environment-Driven Configuration

• All credentials, paths, and message templates are configurable via environment variables
• Custom .env loader built into the server (no external dependency needed)
• Source number, API key, subaccount ID, API base URL, webhook path, and auth token are all configurable

--

Tech Stack

Notable: The entire service is a single-file Node.js server with zero npm dependencies. No Express, no Fastify, no external packages. This was a deliberate choice to minimize the deployment footprint and eliminate supply chain risk for a compliance-critical service.

--

Key Features

• Zero-Dependency Architecture: Single-file Node.js server using only native modules. No npm packages required at runtime.
• TCPA-Compliant Keyword Handling: Implements the three required keyword responses (STOP, HELP, JOIN) per carrier compliance standards with approved message templates
• Persistent Opt-Out Tracking: JSON-based opt-out store that survives server restarts. Numbers that text STOP are blocked until they text JOIN.
• Bearer Token Webhook Security: Optional authentication layer to prevent unauthorized webhook submissions
• Configurable Message Templates: All reply messages can be customized via environment variables without code changes
• Health Check Monitoring: Built-in health endpoint showing service status and opt-out count
• Phone Number Normalization: Consistent phone number formatting across opt-out store operations
• Graceful Error Handling: Try/catch wrapping the entire request handler with structured JSON error responses

--

Compliance Message Templates

STOP Response:

a subsidiary brand: You have been unsubscribed and will no longer receive messages. No further action is required.

HELP Response:

a subsidiary brand Support: For help, email support@example.com. Msg & data rates may apply. Reply STOP to cancel.

JOIN Response:

a subsidiary brand: You are now opted-in to receive recurring automated SMS alerts. Msg & data rates may apply. Reply HELP for help, STOP to cancel.

--

Impact / Metrics

--

Status

Built. Pending Live Deployment. The webhook service is fully implemented and starts successfully on localhost. The route has been tested locally with sample 8x8 inbound payloads and responds correctly to STOP, HELP, and JOIN keywords. Live outbound SMS has not been tested because real 8x8 Connect/CPaaS API credentials are not yet available. the 8x8 Connect account access appears to be a provisioning issue at the 8x8 platform level. If 8x8 Connect access cannot be resolved, the fallback plan is to port the phone number to Twilio and implement the same keyword handling there.