Developer Guide: Implementing Sinch Delivery Status & Callbacks with Next.js and Node.js

+-------------+       +-----------------+       +-----------------+       +------------------------+       +----------+
| User        | ----> | Next.js UI      | ----> | Sinch API (Send)| ----> | Sinch Platform         | ----> | End User |
| (Browser)   |       | (Client-Side)   |       | (e.g., SMS)     |       | (Processes & Delivers) | <---- | (Phone)  |
+-------------+       +-----------------+       +-----------------+       +------------------------+       +----------+
                                                      ^     |
                                                      |     | (Callback Request: POST /api/sinch/webhook)
                                                      |     v
                                                +----------------------------+       +----------------+
                                                | Next.js API Route (Node.js)| ----> | Optional DB    |
                                                | (Webhook Handler)          |       | (e.g., Prisma) |
                                                +----------------------------+       +----------------+

npx create-next-app@latest sinch-callbacks-app
cd sinch-callbacks-app

npm install raw-body
# or
yarn add raw-body

npm install @prisma/client
npm install prisma --save-dev
# or
yarn add @prisma/client
yarn add prisma --dev

npx prisma init --datasource-provider postgresql # Or 'sqlite', 'mysql', etc.

# .env.local

# Sinch Webhook Configuration
SINCH_WEBHOOK_SECRET="YOUR_STRONG_SECRET_FOR_HMAC_VALIDATION" # Generate a strong random string

# Sinch API Credentials (If sending messages from the same app)
# SINCH_PROJECT_ID="YOUR_SINCH_PROJECT_ID"
# SINCH_APP_ID="YOUR_SINCH_APP_ID"
# SINCH_ACCESS_KEY_ID="YOUR_SINCH_ACCESS_KEY_ID"
# SINCH_ACCESS_SECRET="YOUR_SINCH_ACCESS_SECRET"

# Database URL (If using Prisma)
# DATABASE_URL="postgresql://user:password@host:port/database?sslmode=require"

sinch-callbacks-app/
├── src/
│   └── app/
│       ├── api/
│       │   └── sinch/
│       │       └── webhook/
│       │           └── route.ts  # <-- Our webhook handler
│       ├── page.tsx              # <-- Main app page (optional UI)
│       └── layout.tsx
├── prisma/                     # <-- (Optional) Prisma schema
│   └── schema.prisma
├── .env.local                  # <-- Your secrets
├── next.config.mjs
├── package.json
└── tsconfig.json

// src/app/api/sinch/webhook/route.ts
import { NextRequest_ NextResponse } from 'next/server';
import crypto from 'crypto';
import getRawBody from 'raw-body';

// --- Configuration ---
const SINCH_WEBHOOK_SECRET = process.env.SINCH_WEBHOOK_SECRET;

if (!SINCH_WEBHOOK_SECRET) {
  console.error(""FATAL ERROR: SINCH_WEBHOOK_SECRET is not set in environment variables."");
  // In a real app_ you might prevent startup or throw a more specific error.
  // For this example_ we'll let requests fail later if the secret is missing.
}

// --- Helper Function: Verify HMAC Signature ---
// Reference: https://developers.sinch.com/docs/conversation/callbacks/#authenticating-callbacks
async function verifySinchSignature(req: NextRequest_ rawBody: Buffer): Promise<boolean&gt; {
  if (!SINCH_WEBHOOK_SECRET) {
    console.error(""HMAC validation skipped: SINCH_WEBHOOK_SECRET is not configured."");
    return false; // Or throw an error depending on desired strictness
  }

  const signatureHeader = req.headers.get('x-sinch-webhook-signature');
  const timestampHeader = req.headers.get('x-sinch-webhook-signature-timestamp');
  const nonceHeader = req.headers.get('x-sinch-webhook-signature-nonce');
  const algorithmHeader = req.headers.get('x-sinch-webhook-signature-algorithm');

  if (!signatureHeader || !timestampHeader || !nonceHeader || !algorithmHeader) {
    console.warn('HMAC validation failed: Missing required Sinch signature headers.');
    return false;
  }

  // Currently, Sinch only uses HmacSHA256
  if (algorithmHeader !== 'HmacSHA256') {
    console.warn(`HMAC validation failed: Unsupported algorithm: ${algorithmHeader}`);
    return false;
  }

  // Construct the signed data string: rawBody.nonce.timestamp
  // IMPORTANT: Use the rawBody Buffer directly, DO NOT parse as JSON first.
  const signedData = `${rawBody.toString('utf-8')}.${nonceHeader}.${timestampHeader}`;

  // Calculate the expected signature
  const calculatedSignature = crypto
    .createHmac('sha256', SINCH_WEBHOOK_SECRET)
    .update(signedData)
    .digest('base64');

  // Compare signatures using a timing-safe method (though less critical here than password hashes)
  const expectedSignature = signatureHeader;

  // Basic comparison (sufficient for most cases unless hyper-concerned about timing attacks)
   if (calculatedSignature !== expectedSignature) {
     console.warn('HMAC validation failed: Signatures do not match.');
     console.log(`Received Signature: ${expectedSignature}`);
     console.log(`Calculated Signature: ${calculatedSignature}`);
     return false;
   }

   // Optional: Add nonce/timestamp validation to prevent replay attacks
   // - Store recently seen nonces (e.g., in Redis or memory cache with TTL)
   // - Check if timestamp is within an acceptable window (e.g., 5 minutes)

  return true;
}

// --- POST Handler for Sinch Callbacks ---
export async function POST(req: NextRequest) {
  console.log(`\n--- Received Sinch Callback ---`);
  console.log(`Timestamp: ${new Date().toISOString()}`);
  console.log(`Headers: ${JSON.stringify(Object.fromEntries(req.headers.entries()))}`);

  let rawBody: Buffer;
  try {
    // Read the raw request body stream. This is necessary for HMAC verification
    // as Next.js App Router doesn't have a built-in way to disable body parsing like Pages Router.
    // We need the untouched raw body *before* any potential JSON parsing.
    // Note: Pass the ReadableStream from req.body directly
    rawBody = await getRawBody(req.body as any); // Type assertion needed
    console.log('Raw Body Received (length):', rawBody.length);
  } catch (error: any) {
    console.error('Error reading raw request body:', error);
    return new NextResponse(JSON.stringify({ error: 'Failed to read request body' }), {
      status: 400,
      headers: { 'Content-Type': 'application/json' },
    });
  }

  // --- 1. Verify HMAC Signature ---
  const isSignatureValid = await verifySinchSignature(req, rawBody);
  if (!isSignatureValid) {
    console.error('Invalid Sinch signature. Rejecting request.');
    // Respond with 401 Unauthorized if signature is invalid
    return new NextResponse(JSON.stringify({ error: 'Invalid signature' }), {
      status: 401,
      headers: { 'Content-Type': 'application/json' },
    });
  }
  console.log('HMAC Signature Verified Successfully.');

  // --- 2. Process the Callback (After successful verification) ---
  try {
    // Now that signature is verified, parse the JSON payload safely
    const callbackPayload = JSON.parse(rawBody.toString('utf-8'));

    console.log('Parsed Callback Payload:', JSON.stringify(callbackPayload, null, 2));

    // --- !!! IMPORTANT: Respond Quickly !!! ---
    // Acknowledge receipt to Sinch IMMEDIATELY before doing heavy processing.
    // Sinch expects a 2xx response quickly, otherwise it will retry.
    // Perform database updates, notifications, etc., asynchronously if needed.

    // Example: Log the event type (adjust based on actual payload structure)
    if (callbackPayload.message_delivery_report) {
        console.log(`Processing MESSAGE_DELIVERY: Status - ${callbackPayload.message_delivery_report.status}, Message ID - ${callbackPayload.message_delivery_report.message_id}`);
        // TODO: Add database update logic here (e.g., update message status)
    } else if (callbackPayload.message) { // Check for inbound message structure
        console.log(`Processing MESSAGE_INBOUND: From - ${callbackPayload.message.channel_identity?.identity}, Message ID - ${callbackPayload.message.id}`);
        // TODO: Handle inbound message logic
    } else {
        // Log the first top-level key as a hint for unknown types
        console.log('Processing other callback type. Top-level key:', Object.keys(callbackPayload)[0] || 'Unknown Type');
        // TODO: Handle other event types as needed based on your subscribed triggers
    }

    // --- Asynchronous Processing (Example Pattern) ---
    // If processing takes time (DB writes, external API calls), do it without blocking the response.
    // Don't use 'await' here if it delays the response significantly.
    /*
    processCallbackAsync(callbackPayload).catch(err =&gt; {
        console.error(""Error during async callback processing:"", err);
        // Implement proper error tracking (e.g., Sentry)
    });
    */

    // --- 3. Send Success Response to Sinch ---
    // Return 200 OK to Sinch to acknowledge receipt.
    return new NextResponse(JSON.stringify({ message: 'Callback received successfully' }), {
      status: 200,
      headers: { 'Content-Type': 'application/json' },
    });

  } catch (error: any) {
    console.error('Error processing callback payload:', error);
    // Handle JSON parsing errors or other processing errors
    return new NextResponse(JSON.stringify({ error: 'Failed to process callback' }), {
      status: 500, // Internal Server Error
      headers: { 'Content-Type': 'application/json' },
    });
  }
}

/*
// Example async processing function (if needed)
async function processCallbackAsync(payload: any) {
    console.log(""Starting async processing for payload:"", payload.app_id);
    // Simulate work like database update
    await new Promise(resolve =&gt; setTimeout(resolve, 500)); // Simulate DB write time
    console.log(""Finished async processing for payload:"", payload.app_id);
    // Example: Update database using Prisma
    // await prisma.messageStatus.update({ where: { messageId: payload.message_delivery_report?.message_id }, data: { status: payload.message_delivery_report?.status }});
}
*/

// Optional: Handle other HTTP methods if necessary (Sinch uses POST)
export async function GET(req: NextRequest) {
  return new NextResponse(JSON.stringify({ error: 'Method Not Allowed' }), { status: 405 });
}
// Add PUT, DELETE etc. handlers returning 405 if needed.

# Example using curl (replace placeholders)
curl -X POST \
 'https://eu.conversation.api.sinch.com/v1/projects/{{PROJECT_ID}}/webhooks' \
 -H 'Content-Type: application/json' \
 -H 'Authorization: Bearer {{YOUR_SINCH_ACCESS_TOKEN}}' \ # Use a token generated from your Access Key/Secret
 -d '{
   "app_id": "{{YOUR_SINCH_APP_ID}}",
   "target": "YOUR_PUBLIC_WEBHOOK_URL/api/sinch/webhook",
   "target_type": "HTTP",
   "triggers": [
     "MESSAGE_DELIVERY",
     "MESSAGE_INBOUND"
     # Add other desired triggers here
   ],
   "secret": "YOUR_STRONG_SECRET_FOR_HMAC_VALIDATION" # Must match .env.local
 }'

// prisma/schema.prisma

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

datasource db {
  provider = "postgresql" // Or your chosen provider
  url      = env("DATABASE_URL")
}

model Message {
  id              String    @id @default(cuid()) // Internal DB ID
  sinchMessageId  String    @unique // The ID from Sinch callbacks
  conversationId  String?
  contactId       String?
  channel         String?
  status          String?   // e.g., QUEUED_ON_CHANNEL, DELIVERED, FAILED, READ
  direction       String    // TO_APP (inbound) or TO_CONTACT (outbound - assumed if not inbound)
  content         Json?     // Store parts of the message content if needed
  lastUpdatedAt   DateTime  @updatedAt
  createdAt       DateTime  @default(now())

  // Add relations to Contact or Conversation models if needed
}

// You might also want models for Contacts, Conversations, etc.

// src/app/api/sinch/webhook/route.ts
// ... (imports, config, helpers remain the same)
import { PrismaClient } from '@prisma/client'; // Import Prisma Client

const prisma = new PrismaClient(); // Instantiate Prisma Client

// ... (inside the POST handler, after signature verification and JSON parsing)

    console.log('Parsed Callback Payload:', JSON.stringify(callbackPayload, null, 2));

    // --- Asynchronous Processing REQUIRED for DB operations ---
    processCallbackAsync(callbackPayload).catch(err => {
        console.error("Error during async callback processing:", err);
        // Implement proper error tracking (e.g., Sentry)
    });

    // --- 3. Send Success Response to Sinch ---
    // Return 200 OK to Sinch IMMEDIATELY. DB update happens in the background.
    return new NextResponse(JSON.stringify({ message: 'Callback received successfully' }), {
      status: 200,
      headers: { 'Content-Type': 'application/json' },
    });

// ... (rest of the POST handler error handling)

// --- Async processing function for DB operations ---
async function processCallbackAsync(payload: any) {
    console.log(`Starting async processing for app_id: ${payload.app_id}`);
    try {
        if (payload.message_delivery_report) {
            const report = payload.message_delivery_report;
            console.log(`Async: Processing MESSAGE_DELIVERY: Status - ${report.status}, Message ID - ${report.message_id}`);

            // --- Idempotent Update ---
            // Use upsert: Update if exists, create if not (though ideally outbound messages create the initial record)
            await prisma.message.upsert({
                where: { sinchMessageId: report.message_id },
                update: {
                    status: report.status,
                    // Add other fields to update if necessary
                },
                create: { // This part might only run if the initial send didn't create a record
                    sinchMessageId: report.message_id,
                    status: report.status,
                    direction: 'TO_CONTACT', // Assume delivery reports are for outbound
                    conversationId: report.conversation_id,
                    contactId: report.contact_id,
                    channel: report.channel_identity?.channel,
                    // content: ... // Potentially store initial content elsewhere
                }
            });
            console.log(`Async: DB updated for message ${report.message_id}`);

        } else if (payload.message) { // Handle inbound message
            const msg = payload.message;
            console.log(`Async: Processing MESSAGE_INBOUND: From - ${msg.channel_identity?.identity}, Message ID - ${msg.id}`);

             // --- Idempotent Insert ---
             // Use create with a check or rely on unique constraint
             // For simplicity, just create. Handle potential unique constraint errors if retried.
             await prisma.message.create({
                 data: {
                    sinchMessageId: msg.id,
                    conversationId: msg.conversation_id,
                    contactId: msg.contact_id,
                    channel: msg.channel_identity?.channel,
                    status: 'RECEIVED', // Custom status for inbound
                    direction: msg.direction, // Should be TO_APP
                    content: msg.contact_message || {}, // Store the message content
                 }
             });
            console.log(`Async: DB record created for inbound message ${msg.id}`);

        } else {
             // Log the first top-level key as a hint for unknown types
             console.log('Async: Processing other callback type. Top-level key:', Object.keys(payload)[0] || 'Unknown Type');
            // Handle other event types and update DB accordingly
        }
    } catch (error: any) {
        // Handle potential Prisma errors (e.g., unique constraint violation on retry)
        if (error.code === 'P2002') { // Prisma unique constraint error code
             console.warn(`Async: Record likely already exists for ID (idempotency handled): ${payload.message_delivery_report?.message_id || payload.message?.id}`);
        } else {
             console.error("Async: Error during database operation:", error);
             // Add more robust error logging/reporting
             throw error; // Re-throw to be caught by the outer catch block if needed
        }
    } finally {
         console.log(`Finished async processing for app_id: ${payload.app_id}`);
         // Disconnect Prisma client in serverless environments? Depends on deployment strategy.
         // It's generally recommended *not* to explicitly disconnect in serverless functions
         // as it can interfere with connection pooling and reuse on subsequent invocations.
         // await prisma.$disconnect(); // Often not needed with Vercel/modern platforms
    }
}