SMS Delivery Receipts on AWS Lambda

rates a robust handler with signature verification, payload parsing, and SQS offloading.

import { createHmac, timingSafeEqual } from 'crypto';
import { SSMClient, GetParameterCommand } from '@aws-sdk/client-ssm';
import { SQSClient, SendMessageCommand } from '@aws-sdk/client-sqs';
import { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';

// Interfaces for type safety
interface SinchHeaders {
  'x-sinch-webhook-signature': string;
  'x-sinch-webhook-signature-nonce': string;
  'x-sinch-webhook-signature-timestamp': string;
}

interface DeliveryReport {
  message_id: string;
  status: 'QUEUED_ON_CHANNEL' | 'DELIVERED' | 'FAILED' | 'READ';
  reason?: {
    code: string;
    description: string;
    sub_code?: string;
    channel_code?: string;
  };
  channel_identity?: {
    channel: string;
    identity: string;
  };
}

interface WebhookPayload {
  message_delivery_report: DeliveryReport;
  app_id: string;
  project_id: string;
  event_time: string;
}

// Singleton clients for reuse across invocations
const ssmClient = new SSMClient({});
const sqsClient = new SQSClient({});

let cachedSecret: string | null = null;

async function retrieveWebhookSecret(paramName: string): Promise<string> {
  if (cachedSecret) return cachedSecret;

  const response = await ssmClient.send(
    new GetParameterCommand({
      Name: paramName,
      WithDecryption: true,
    })
  );

  if (!response.Parameter?.Value) {
    throw new Error('Webhook secret not found in SSM');
  }

  cachedSecret = response.Parameter.Value;
  return cachedSecret;
}

function verifyIntegrity(
  body: string,
  signature: string,
  nonce: string,
  timestamp: string,
  secret: string
): boolean {
  const payload = `${body}.${nonce}.${timestamp}`;
  const expectedSignature = createHmac('sha256', secret)
    .update(payload)
    .digest('base64');

  // Timing-safe comparison to prevent timing attacks
  return (
    signature.length === expectedSignature.length &&
    timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))
  );
}

export const handler = async (
  event: APIGatewayProxyEvent
): Promise<APIGatewayProxyResult> => {
  try {
    const headers = event.headers as unknown as SinchHeaders;
    const body = event.body || '';

    // 1. Validate required headers
    const signature = headers['x-sinch-webhook-signature'];
    const nonce = headers['x-sinch-webhook-signature-nonce'];
    const timestamp = headers['x-sinch-webhook-signature-timestamp'];

    if (!signature || !nonce || !timestamp) {
      return { statusCode: 400, body: 'Missing signature headers' };
    }

    // 2. Retrieve secret and verify HMAC
    const secretParam = process.env.WEBHOOK_SECRET_PARAM!;
    const secret = await retrieveWebhookSecret(secretParam);

    const isValid = verifyIntegrity(body, signature, nonce, timestamp, secret);
    if (!isValid) {
      console.error('HMAC verification failed');
      return { statusCode: 401, body: 'Invalid signature' };
    }

    // 3. Parse and validate payload
    const payload: WebhookPayload = JSON.parse(body);
    if (!payload.message_delivery_report) {
      return { statusCode: 400, body: 'Invalid payload structure' };
    }

    // 4. Offload to SQS for async processing
    const queueUrl = process.env.DELIVERY_QUEUE_URL!;
    await sqsClient.send(
      new SendMessageCommand({
        QueueUrl: queueUrl,
        MessageBody: JSON.stringify(payload),
        MessageGroupId: payload.message_delivery_report.message_id, // FIFO ordering if needed
      })
    );

    // 5. Acknowledge immediately
    return { statusCode: 200, body: 'OK' };
  } catch (error) {
    console.error('Webhook processing error:', error);
    // Return 500 to trigger Sinch retry on transient errors
    return { statusCode: 500, body: 'Internal error' };
  }
};

Rationale:

• Timing-Safe Comparison: timingSafeEqual prevents timing side-channel attacks during signature verification.
• SQS Integration: Decoupling ensures the Lambda returns 200 within milliseconds, satisfying Sinch's latency requirements and preventing unnecessary retries.
• Error Handling: Returning 500 on internal errors triggers Sinch's exponential backoff retry mechanism. Returning 400 or 401 indicates a permanent failure, stopping retries.

Pitfall Guide

1. Treating the First Callback as Final

   • Explanation: Sinch sends multiple callbacks per message. The first is often QUEUED_ON_CHANNEL. Assuming this is the final status leads to incorrect reporting.
   • Fix: Implement a state machine or update logic that tracks the latest status. Only treat DELIVERED or FAILED as terminal states.

2. Blocking the Callback Handler

   • Explanation: Performing database writes or external API calls inside the Lambda handler increases latency. If the handler times out or responds slowly, Sinch may retry the callback, causing duplicates.
   • Fix: Always return 200 OK immediately after validation. Push processing to SQS or EventBridge.

3. Assuming Sequential Callback Order

   • Explanation: Network conditions can cause callbacks to arrive out of order. A DELIVERED event might arrive before QUEUED_ON_CHANNEL.
   • Fix: Design idempotent updaters that rely on the message_id and event_time. Do not assume callbacks arrive in chronological order.

4. Missing Deduplication Logic

   • Explanation: Sinch may deliver duplicate callbacks due to network glitches or retry mechanisms.
   • Fix: Use message_id combined with status as a deduplication key. Check if the status has already been processed before updating downstream systems.

5. Misinterpreting 4xx Responses

   • Explanation: Sinch retries on 5xx and 429 but treats 4xx (except 429) as permanent failures. If your handler returns 400 due to a parsing error, Sinch stops retrying, and you lose the receipt.
   • Fix: Ensure robust parsing. If a payload is malformed but the signature is valid, log the error and return 200 to acknowledge receipt, or return 500 to trigger a retry if the error is transient.

6. Hardcoding Secrets

   • Explanation: Embedding the webhook secret in code or environment variables without encryption risks exposure.
   • Fix: Store secrets in AWS SSM Parameter Store or Secrets Manager. Use SecureString types and IAM roles to restrict access.

7. Ignoring Failure Reason Codes

   • Explanation: FAILED status includes a reason object with codes like RECIPIENT_NOT_REACHABLE or CHANNEL_FAILURE. Ignoring these prevents targeted error handling.
   • Fix: Parse the reason.code to implement specific logic. For example, RECIPIENT_INVALID_CHANNEL_IDENTITY might indicate a typo in the user's phone number, triggering a data correction workflow.

Production Bundle

Action Checklist

• Register Webhook: Configure the Sinch Conversation API webhook with the MESSAGE_DELIVERY trigger and your Lambda Function URL.
• Secure Secret: Store the webhook secret in SSM Parameter Store as a SecureString and reference it via IAM permissions.
• Implement HMAC: Add signature verification using crypto.createHmac and timingSafeEqual to prevent spoofing.
• Add Metadata: Include message_metadata in your messages:send requests to correlate receipts with business entities (e.g., order IDs, user IDs).
• Decouple Processing: Route webhook payloads to an SQS queue to ensure low-latency acknowledgment and reliable processing.
• Handle States: Update your database to track QUEUED, DELIVERED, and FAILED states separately. Do not overwrite terminal states.
• Monitor Failures: Set up CloudWatch Alarms for spikes in FAILED status receipts to detect carrier issues or configuration errors.
• Test Edge Cases: Verify handling of disconnected numbers, invalid formats, and duplicate callbacks in a staging environment.

Decision Matrix

Configuration Template

AWS SAM template snippet for deploying the webhook infrastructure.

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31

Parameters:
  WebhookSecretParam:
    Type: String
    Description: SSM Parameter name for the webhook secret
    Default: /sinch/webhook-secret

Resources:
  DeliveryReceiptFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: src/
      Handler: webhook.handler
      Runtime: nodejs20.x
      Environment:
        Variables:
          WEBHOOK_SECRET_PARAM: !Ref WebhookSecretParam
          DELIVERY_QUEUE_URL: !Ref DeliveryQueue
      Policies:
        - SSMParameterReadPolicy:
            ParameterName: !Ref WebhookSecretParam
        - SQSSendMessagePolicy:
            QueueName: !GetAtt DeliveryQueue.QueueName
      FunctionUrlConfig:
        AuthType: NONE
        Cors:
          AllowOrigins:
            - "*"

  DeliveryQueue:
    Type: AWS::SQS::Queue
    Properties:
      VisibilityTimeout: 30
      MessageRetentionPeriod: 1209600 # 14 days

  DeliveryProcessor:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: src/
      Handler: processor.handler
      Runtime: nodejs20.x
      Events:
        QueueEvent:
          Type: SQS
          Properties:
            Queue: !GetAtt DeliveryQueue.Arn
            BatchSize: 10

Outputs:
  FunctionUrl:
    Description: "Lambda Function URL for Sinch Webhook"
    Value: !GetAtt DeliveryReceiptFunctionUrl.FunctionUrl

Quick Start Guide

1. Deploy Infrastructure: Run sam build and sam deploy to provision the Lambda, SQS queue, and Function URL. Note the output URL.
2. Store Secret: Use the AWS CLI to create the SSM parameter:

   aws ssm put-parameter \
     --name /sinch/webhook-secret \
     --value "your-generated-secret" \
     --type SecureString
   

3. Register Webhook: In the Sinch Dashboard, navigate to Conversation API > Apps > Webhooks. Add a new webhook with the Function URL, paste the secret, and select MESSAGE_DELIVERY as the trigger.
4. Send Test Message: Trigger an SMS via your application or the Sinch dashboard.
5. Verify Receipts: Check CloudWatch Logs for the Lambda function to confirm 200 responses. Inspect the SQS queue or downstream database to verify the delivery status was processed correctly.