This library provides constructs for adding destinations to a Lambda function. Destinations can be added by specifying the onFailure or onSuccess props when creating a function or alias.

The following destinations are supported

• Lambda function
• SQS queue - Only standard SQS queues are supported for failure destinations, FIFO queues are not supported.
• SNS topic
• EventBridge event bus
• S3 bucket

Example with a SNS topic for successful invocations:

import * as sns from 'aws-cdk-lib/aws-sns';

const myTopic = new sns.Topic(this, 'Topic');

const myFn = new lambda.Function(this, 'Fn', {
  runtime: lambda.Runtime.NODEJS_LATEST,
  handler: 'index.handler',
  code: lambda.Code.fromAsset(path.join(__dirname, 'lambda-handler')),
  
  onSuccess: new destinations.SnsDestination(myTopic),
})

Example not in your language?

Example with a SQS queue for unsuccessful invocations:

import * as sqs from 'aws-cdk-lib/aws-sqs';

const deadLetterQueue = new sqs.Queue(this, 'DeadLetterQueue');

const myFn = new lambda.Function(this, 'Fn', {
  runtime: lambda.Runtime.NODEJS_LATEST,
  handler: 'index.handler',
  code: lambda.Code.fromInline('// your code'),
  
  onFailure: new destinations.SqsDestination(deadLetterQueue),
});

Example not in your language?

See also Configuring Destinations for Asynchronous Invocation.

When a lambda function is configured with a destination, an invocation record is created by the Lambda service when the lambda function completes. The invocation record contains the details of the function, its context, and the request and response payloads.

The following example shows the format of the invocation record for a successful invocation:

{
    "version": "1.0",
    "timestamp": "2019-11-24T23:08:25.651Z",
    "requestContext": {
        "requestId": "c2a6f2ae-7dbb-4d22-8782-d0485c9877e2",
        "functionArn": "arn:aws:lambda:sa-east-1:123456789123:function:event-destinations:$LATEST",
        "condition": "Success",
        "approximateInvokeCount": 1
    },
    "requestPayload": {
        "Success": true
    },
    "responseContext": {
        "statusCode": 200,
        "executedVersion": "$LATEST"
    },
    "responsePayload": "<data returned by the function here>"
}

Example not in your language?

In case of failure, the record contains the reason and error object:

{
  "version": "1.0",
  "timestamp": "2019-11-24T21:52:47.333Z",
  "requestContext": {
    "requestId": "8ea123e4-1db7-4aca-ad10-d9ca1234c1fd",
    "functionArn": "arn:aws:lambda:sa-east-1:123456678912:function:event-destinations:$LATEST",
    "condition": "RetriesExhausted",
    "approximateInvokeCount": 3
  },
  "requestPayload": {
    "Success": false
  },
  "responseContext": {
    "statusCode": 200,
    "executedVersion": "$LATEST",
    "functionError": "Handled"
  },
  "responsePayload": {
    "errorMessage": "Failure from event, Success = false, I am failing!",
    "errorType": "Error",
    "stackTrace": [ "exports.handler (/var/task/index.js:18:18)" ]
  }
}

Example not in your language?

• For SNS/SQS (SnsDestionation/SqsDestination), the invocation record JSON is passed as the Message to the destination.
• For Lambda (LambdaDestination), the invocation record JSON is passed as the payload to the function.
• For EventBridge (EventBridgeDestination), the invocation record JSON is passed as the detail in the PutEvents call. The value for the event field source is lambda, and the value for the event field detail-type is either 'Lambda Function Invocation Result - Success' or 'Lambda Function Invocation Result – Failure', depending on whether the lambda function invocation succeeded or failed. The event field resource contains the function and destination ARNs. See AWS Events for the different event fields.
• For S3 (S3Destination), the invocation record json is stored as a File in the destination bucket. The path of a destination payload file in the configured bucket is aws/lambda/async/<function-name>/YYYY/MM/DD/YYYY-MM-DDTHH.MM.SS-<Random UUID>.

The responseOnly option of LambdaDestination allows to auto-extract the response payload from the invocation record:

declare const destinationFn: lambda.Function;

const sourceFn = new lambda.Function(this, 'Source', {
  runtime: lambda.Runtime.NODEJS_LATEST,
  handler: 'index.handler',
  code: lambda.Code.fromAsset(path.join(__dirname, 'lambda-handler')),
  
  onSuccess: new destinations.LambdaDestination(destinationFn, {
    responseOnly: true,
  }),
})

Example not in your language?

In the above example, destinationFn will be invoked with the payload returned by sourceFn (responsePayload in the invocation record, not the full record).

When used with onFailure, the destination function is invoked with the error object returned by the source function.

Using the responseOnly option allows to easily chain asynchronous Lambda functions without having to deal with data extraction in the runtime code.