Node.js Lambda crashing on Genesys Cloud EventBridge webhook parsing

Stumbled on a weird bug today with my Node.js Lambda function that processes Genesys Cloud EventBridge notifications. I’m trying to extract the conversationId from the detail object to update a record in Salesforce via middleware, but the payload structure seems inconsistent between test events and actual production triggers.

Here is my handler:

exports.handler = async (event) => {
 console.log('Event:', JSON.stringify(event, null, 2));
 try {
 const detail = event.detail || event.Records[0].Sns.Message;
 const convId = detail.conversationId;
 if (!convId) throw new Error('Missing conversationId');
 // ... call Salesforce API
 } catch (err) {
 console.error(err);
 return { statusCode: 500, body: 'Failed' };
 }
};

When I invoke it with a raw HTTP POST (mimicking the webhook), event.detail is undefined, and event.Records is also empty. However, when I use the EventBridge console to send a test event, it works fine. I’m running Node.js 18.x in the Lambda environment. Is there a specific wrapper or header I need to check for the actual Genesys Cloud push? I see a 400 Bad Request in CloudWatch when the actual webhook fires, implying the payload shape is totally different than the EventBridge simulation. Any hints on the exact JSON path for a real-time conversation update event?

const convId = event.detail?.conversationId || event.body?.conversationId;

I usually solve this by checking both event.detail and event.body. EventBridge wraps the payload, so event.detail is correct for production. Test events often mimic API requests, putting data in event.body. This conditional prevents undefined errors when switching environments.

The conditional check works, but event.detail is a stringified JSON blob, not an object. You need JSON.parse(event.detail).conversationId to access the property.

Make sure you validate the payload type before parsing. The suggestion above handles the object path, but it ignores that event.detail is often a serialized string in EventBridge integrations. If you pass a string to property accessors, you get undefined, which breaks downstream middleware. Also, never trust the structure implicitly; Genesys Cloud notification payloads can vary based on the subscription filter.

Here is the robust pattern for Node.js Lambda handlers processing Genesys Cloud webhooks:

1. Check if event.detail is a string.
2. Parse it safely with JSON.parse.
3. Extract the conversationId from the resulting object.
4. Handle potential parse errors to avoid Lambda crashes.

exports.handler = async (event) => {
 let detailObj = event.detail;
 
 // Step 1 & 2: Handle stringified JSON from EventBridge
 if (typeof detailObj === 'string') {
 try {
 detailObj = JSON.parse(detailObj);
 } catch (e) {
 console.error('Failed to parse event.detail:', e);
 return { statusCode: 500, body: 'Parse error' };
 }
 }

 // Step 3: Extract conversationId
 const convId = detailObj?.conversationId;

 if (!convId) {
 console.warn('No conversationId found in payload');
 return { statusCode: 200, body: 'No ID' };
 }

 // Step 4: Process
 console.log(`Processing conversation: ${convId}`);
 // Call your Salesforce middleware here
 return { statusCode: 200, body: JSON.stringify({ processed: true, id: convId }) };
};

This approach prevents the TypeError: Cannot read property 'conversationId' of undefined crash. It also aligns with how the Genesys Cloud Notification API serializes data for external endpoints. If you are using the PureCloudPlatformClientV2 SDK for validation elsewhere, remember that the webhook payload is raw JSON, not a typed SDK model. You must handle the deserialization manually in the Lambda context. Check your CloudWatch logs for the raw event structure if the ID is still missing; sometimes the detail contains a nested data object depending on the subscription configuration.