Sinch SMS Delivery Status Callbacks in RedwoodJS: Complete Implementation Guide

# Using Yarn
yarn create redwood-app ./sinch-redwood-callbacks

# Or using npm
npx create-redwood-app ./sinch-redwood-callbacks

cd sinch-redwood-callbacks

touch .env

# .env

# --- Database ---
# Replace with your actual database connection string
# Example for PostgreSQL: DATABASE_URL="postgresql://user:password@host:port/database?schema=public"
# Example for SQLite (default): DATABASE_URL="file:./dev.db"
DATABASE_URL="file:./dev.db"

# --- Sinch API Credentials ---
# Found on your Sinch Customer Dashboard under your API/Service Plan
SINCH_SERVICE_PLAN_ID="YOUR_SERVICE_PLAN_ID"
SINCH_API_TOKEN="YOUR_API_TOKEN"

# --- Sinch Webhook Security ---
# A secret string you create. Must match the secret configured in the Sinch Dashboard for the callback URL.
# Generate a strong random string (e.g., using `openssl rand -hex 32`, a password manager, or other secure generator)
SINCH_WEBHOOK_SECRET="YOUR_STRONG_RANDOM_SECRET_STRING"

# --- RedwoodJS Logger ---
# Optional: Set log level (trace, debug, info, warn, error, fatal)
LOG_LEVEL="info"

yarn rw prisma migrate dev --name initial_setup

yarn rw g function sinchCallbacks --ts

// api/src/functions/sinchCallbacks.ts
import type { APIGatewayEvent, Context } from 'aws-lambda'
import { logger } from 'src/lib/logger'

/**
 * The handler function is your code that processes http request events.
 * You already have access to the logger and use it to log any errors.
 *
 * @typedef { import('aws-lambda').APIGatewayEvent } APIGatewayEvent
 * @typedef { import('aws-lambda').Context } Context
 * @param { APIGatewayEvent } event - an object which contains information from the invoker.
 * @param { Context } context - contains information about the invocation,
 * function, and execution environment.
 */
export const handler = async (event: APIGatewayEvent, context: Context) => {
  logger.info('Incoming request to sinchCallbacks function')

  // Basic validation: Ensure it's a POST request
  if (event.httpMethod !== 'POST') {
    logger.warn('Received non-POST request')
    return {
      statusCode: 405, // Method Not Allowed
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ error: 'Method Not Allowed' }),
    }
  }

  // TODO: Add HMAC Signature Validation
  // TODO: Parse Request Body
  // TODO: Process Callback Data (using a Service)
  // TODO: Return appropriate response to Sinch

  return {
    statusCode: 200, // Placeholder: Acknowledge receipt
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ message: 'Callback received' }),
  }
}

{
  "type": "recipient_delivery_report_sms",
  "batch_id": "01FC66621XXXXX119Z8PMV1QPQ",
  "recipient": "+15551231234",
  "code": 401,
  "status": "Dispatched",
  "at": "2022-08-30T08:16:08.930Z",
  "operator_status_at": "2022-08-30T08:16:08.900Z",
  "client_reference": "your_optional_reference_123"
}

# NOTE: Replace YOUR_ENDPOINT_URL with your actual ngrok or deployed URL
# NOTE: This example does *not* include the HMAC signature yet.
curl -X POST \
  YOUR_ENDPOINT_URL/api/sinchCallbacks \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "recipient_delivery_report_sms",
    "batch_id": "TEST_BATCH_ID_123",
    "recipient": "+15559998888",
    "code": 0,
    "status": "Delivered",
    "at": "2025-04-20T10:00:00.000Z"
  }'

# Replace placeholders with your actual values
SINCH_SERVICE_PLAN_ID="YOUR_SERVICE_PLAN_ID"
SINCH_API_TOKEN="YOUR_API_TOKEN"
YOUR_SINCH_NUMBER_OR_ALPHANUMERIC="YOUR_SENDER_ID"

curl -X POST \
  "https://us.sms.api.sinch.com/xms/v1/${SINCH_SERVICE_PLAN_ID}/batches" \
  -H "Authorization: Bearer ${SINCH_API_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "'${YOUR_SINCH_NUMBER_OR_ALPHANUMERIC}'",
    "to": [ "+15551234567" ],
    "body": "Hello from RedwoodJS!",
    "delivery_report": "per_recipient",
    "client_reference": "optional_your_ref_123"
  }'

// api/src/functions/sinchCallbacks.ts
import type { APIGatewayEvent, Context } from 'aws-lambda'
import { logger } from 'src/lib/logger'
// Import validation function (we'll create this in the Security section)
import { validateSinchSignature } from 'src/lib/sinchSecurity'
// Import the service function (we'll create this in the Data Layer section)
import { recordSmsStatusUpdate } from 'src/services/smsStatus/smsStatus'

// Define an interface for the expected callback payload
interface SinchRecipientDeliveryReport {
  type: 'recipient_delivery_report_sms' | 'recipient_delivery_report_mms' // Focus on SMS
  batch_id: string
  recipient: string
  code: number
  status: string
  at: string // ISO 8601 timestamp string
  operator_status_at?: string
  client_reference?: string
}

export const handler = async (event: APIGatewayEvent, context: Context) => {
  // Use a unique request ID for logging correlation
  const requestId = context.awsRequestId || `local-${Date.now()}`
  const handlerLogger = logger.child({ requestId })
  handlerLogger.info('Incoming request to sinchCallbacks function')

  // 1. Basic Method Validation
  if (event.httpMethod !== 'POST') {
    handlerLogger.warn('Received non-POST request')
    return { statusCode: 405, headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ error: 'Method Not Allowed' }) }
  }

  // 2. HMAC Signature Validation
  try {
    const rawBody = event.body
    if (rawBody === null || rawBody === undefined) {
        handlerLogger.error('Raw request body is missing or null')
        return { statusCode: 400, body: JSON.stringify({ error: 'Bad Request: Missing body' }) }
    }

    const webhookSecret = process.env.SINCH_WEBHOOK_SECRET
    if (!webhookSecret) {
      handlerLogger.error('SINCH_WEBHOOK_SECRET environment variable is not set')
      return { statusCode: 500, body: JSON.stringify({ error: 'Internal Server Error: Webhook secret not configured' }) }
    }

    const isValid = validateSinchSignature(
      event.headers,
      rawBody,
      webhookSecret
    )
    if (!isValid) {
      handlerLogger.error('Invalid Sinch signature')
      return { statusCode: 401, body: JSON.stringify({ error: 'Unauthorized' }) }
    }
    handlerLogger.info('Sinch signature validated successfully')
  } catch (error) {
    handlerLogger.error({ error }, 'Error during signature validation')
    return { statusCode: 400, body: JSON.stringify({ error: 'Signature validation failed' }) }
  }

  // 3. Parse Request Body
  let payload: SinchRecipientDeliveryReport
  try {
    payload = JSON.parse(event.body!)
    handlerLogger.info({ payloadType: payload.type }, 'Parsed request body')

    // Basic payload type check
    if (payload.type !== 'recipient_delivery_report_sms') {
       handlerLogger.warn({ type: payload.type }, 'Received non-SMS recipient report type, ignoring')
       return { statusCode: 200, headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ message: 'Callback type ignored' }) }
    }

  } catch (error) {
    handlerLogger.error({ error, bodySnippet: event.body?.substring(0, 100) }, 'Failed to parse request body')
    return { statusCode: 400, body: JSON.stringify({ error: 'Bad Request: Malformed JSON' }) }
  }

  // 4. Process Callback Data (Using Service)
  try {
    await recordSmsStatusUpdate({
      batchId: payload.batch_id,
      recipient: payload.recipient,
      statusCode: payload.code,
      status: payload.status,
      statusTimestamp: new Date(payload.at),
      clientReference: payload.client_reference,
      rawPayload: event.body!,
    })

    handlerLogger.info({ batchId: payload.batch_id, recipient: payload.recipient, status: payload.status }, 'Successfully processed Sinch callback')

    // 5. Return Success Response to Sinch
    // IMPORTANT: Always return 2xx to Sinch upon successful receipt,
    // even if your internal processing encounters a recoverable issue.
    // This prevents Sinch from retrying unnecessarily.
    return {
      statusCode: 200,
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ message: 'Callback processed successfully' }),
    }

  } catch (error) {
    handlerLogger.error({ error, batchId: payload.batch_id, recipient: payload.recipient }, 'Error processing Sinch callback in service')
    // Even on internal error, acknowledge receipt to Sinch
    return {
      statusCode: 200, // Acknowledge receipt to prevent Sinch retries
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ message: 'Callback received but internal processing failed' }),
    }
  }
}

// api/db/schema.prisma

datasource db {
  provider = "sqlite" // Or "postgresql", "mysql"
  url      = env("DATABASE_URL")
}

generator client {
  provider      = "prisma-client-js"
  binaryTargets = "native"
}

// Model representing an SMS message sent via Sinch
model Message {
  id            String   @id @default(cuid())
  createdAt     DateTime @default(now())
  updatedAt     DateTime @updatedAt

  to            String   // Recipient phone number. Store in E.164 format to match Sinch callbacks.
  body          String?
  sentAt        DateTime @default(now())
  sinchBatchId  String   // The Batch ID returned by Sinch
  clientReference String?

  // Track the latest known status
  latestStatus        String?
  latestStatusCode    Int?
  latestStatusTimestamp DateTime?

  // Relation to status updates
  statusUpdates SmsStatusUpdate[]

  @@index([sinchBatchId])
  @@index([clientReference])
  @@index([to])
}

// Model representing a delivery status update received from Sinch
model SmsStatusUpdate {
  id            String   @id @default(cuid())
  createdAt     DateTime @default(now())

  messageId     String
  message       Message  @relation(fields: [messageId], references: [id], onDelete: Cascade)

  sinchBatchId  String
  recipient     String
  status        String   // e.g., "Dispatched", "Delivered", "Failed"
  statusCode    Int      // e.g., 401, 0, 402 (Sinch status codes)
  statusTimestamp DateTime

  clientReference String?
  rawPayload    String   // Store the full JSON payload for auditing

  @@index([messageId])
  @@index([sinchBatchId, recipient])
  @@index([statusTimestamp])
}

yarn rw prisma migrate dev --name add_message_and_status_tables

yarn rw g service smsStatus --ts

// api/src/services/smsStatus/smsStatus.ts
import type { Prisma } from '@prisma/client'
import { db } from 'src/lib/db'
import { logger } from 'src/lib/logger'

interface RecordSmsStatusInput {
  batchId: string
  recipient: string
  statusCode: number
  status: string
  statusTimestamp: Date
  clientReference?: string
  rawPayload: string
}

export const recordSmsStatusUpdate = async ({
  batchId,
  recipient,
  statusCode,
  status,
  statusTimestamp,
  clientReference,
  rawPayload,
}: RecordSmsStatusInput): Promise<void> => {
  const serviceLogger = logger.child({
    batchId,
    recipient,
    status,
    functionName: 'recordSmsStatusUpdate',
  })
  serviceLogger.info('Attempting to record SMS status update')

  // 1. Find the original message
  // CRITICAL: Store recipient in Message.to in E.164 format to match Sinch callbacks.
  // Mismatched formats will prevent finding the message.
  const message = await db.message.findFirst({
    where: {
      sinchBatchId: batchId,
      to: recipient, // Must match format (E.164 recommended)
    },
    select: { id: true, latestStatusTimestamp: true },
  })

  if (!message) {
    serviceLogger.error(
      { clientReference },
      'Could not find original message for this status update. Verify recipient format (E.164) and that the message was stored.'
    )
    throw new Error(
      `Original message not found for batchId: ${batchId}, recipient: ${recipient}. Verify recipient format.`
    )
  }

  serviceLogger.info({ messageId: message.id }, 'Found corresponding message')

  // 2. Create the SmsStatusUpdate record
  try {
    const createData: Prisma.SmsStatusUpdateCreateInput = {
      message: { connect: { id: message.id } },
      sinchBatchId: batchId,
      recipient: recipient,
      status: status,
      statusCode: statusCode,
      statusTimestamp: statusTimestamp,
      clientReference: clientReference,
      rawPayload: rawPayload,
    }

    // Idempotency Check: Avoid duplicates if Sinch retries
    const existingUpdate = await db.smsStatusUpdate.findFirst({
      where: {
        messageId: message.id,
        recipient: recipient,
        status: status,
        statusCode: statusCode,
      },
      select: { id: true }
    });

    if (existingUpdate) {
       serviceLogger.warn({ existingUpdateId: existingUpdate.id }, 'Duplicate status update received, ignoring')
       return;
    }

    const newStatusUpdate = await db.smsStatusUpdate.create({ data: createData })
    serviceLogger.info(
      { statusUpdateId: newStatusUpdate.id },
      'Created new SmsStatusUpdate record'
    )

    // 3. Update the latest status on the parent Message (if newer)
    if (
      !message.latestStatusTimestamp ||
      statusTimestamp > message.latestStatusTimestamp
    ) {
      await db.message.update({
        where: { id: message.id },
        data: {
          latestStatus: status,
          latestStatusCode: statusCode,
          latestStatusTimestamp: statusTimestamp,
        },
      })
      serviceLogger.info({ messageId: message.id }, 'Updated latest status on Message record')
    } else {
      serviceLogger.info(
         { messageId: message.id, newStatusTimestamp: statusTimestamp, latestStatusTimestamp: message.latestStatusTimestamp },
         'Received older or same-timestamp status update, not updating latest status'
       )
    }

  } catch (error) {
    serviceLogger.error({ error }, 'Database error while recording status update')
    throw error
  }
}

// api/src/lib/sinchSecurity.ts
import crypto from 'crypto'
import { logger } from 'src/lib/logger'
import type { APIGatewayProxyEventHeaders } from 'aws-lambda'

/**
 * Find a header value case-insensitively
 */
const findHeader = (headers: APIGatewayProxyEventHeaders, headerName: string): string | undefined => {
  const lowerCaseHeaderName = headerName.toLowerCase();
  const headerKey = Object.keys(headers).find(key => key.toLowerCase() === lowerCaseHeaderName);
  return headerKey ? headers[headerKey] : undefined;
}

/**
 * Validate the Sinch webhook signature using HMAC-SHA256
 *
 * @param headers - Request headers (case-insensitive lookup)
 * @param rawBody - Raw, unparsed request body string (exact bytes received)
 * @param secret - Your Sinch Webhook Secret from environment variables
 * @returns true if signature is valid, false otherwise
 * @throws Error if required headers are missing or secret is invalid
 */
export const validateSinchSignature = (
  headers: APIGatewayProxyEventHeaders,
  rawBody: string,
  secret: string | undefined
): boolean => {
  const securityLogger = logger.child({ functionName: 'validateSinchSignature' })

  if (!secret) {
    securityLogger.error('Webhook secret is not provided or empty')
    throw new Error('Webhook secret is missing or invalid');
  }

  // 1. Extract Sinch headers
  const sinchTimestamp = findHeader(headers, 'x-sinch-timestamp')
  const sinchSignatureHeader = findHeader(headers, 'x-sinch-signature')

  if (!sinchTimestamp) {
    securityLogger.warn('Missing x-sinch-timestamp header')
    return false
  }

  if (!sinchSignatureHeader) {
    securityLogger.warn('Missing x-sinch-signature header')
    return false
  }

  // 2. Prepare the signed content string
  // Sinch typically signs: raw request body + timestamp header value
  // IMPORTANT: Verify this format against current Sinch documentation
  const stringToSign = rawBody + sinchTimestamp;
  securityLogger.debug({ stringToSignLength: stringToSign.length }, 'Constructed string-to-sign')

  // 3. Decode the secret (Sinch secrets are Base64 encoded)
  let decodedSecret: Buffer;
  try {
    decodedSecret = Buffer.from(secret, 'base64');
  } catch (e) {
    securityLogger.error({ error: e }, 'Failed to decode webhook secret from Base64')
    throw new Error('Invalid webhook secret encoding');
  }

  // 4. Calculate the expected signature
  const hmac = crypto.createHmac('sha256', decodedSecret);
  const expectedSignature = hmac.update(stringToSign).digest('base64');
  securityLogger.debug('Calculated expected signature');

  // 5. Compare signatures securely
  const providedSignature = sinchSignatureHeader;

  try {
    const providedSigBuffer = Buffer.from(providedSignature, 'base64');
    const expectedSigBuffer = Buffer.from(expectedSignature, 'base64');

    if (providedSigBuffer.length !== expectedSigBuffer.length) {
        securityLogger.warn('Signature length mismatch');
        return false;
    }

    const isValid = crypto.timingSafeEqual(providedSigBuffer, expectedSigBuffer);
    securityLogger.info(`Signature validation result: ${isValid}`);
    return isValid;

  } catch (error) {
    securityLogger.error({ error }, 'Error during signature comparison (possibly invalid Base64 format)');
    return false;
  }
}

yarn rw dev

ngrok http 8911