Menu
Amazon CloudFront
Developer Guide (API Version 2016-09-29)

Event Structure

The following examples show request and response events.

Request Event

Here's the format of the event object that CloudFront passes to a Lambda function when the function is triggered by a CloudFront viewer request event or an origin request event.

Copy
{ "Records": [ { "cf": { "config": { "distributionId": "EDFDVBD6EXAMPLE" }, "request": { "clientIp": "2001:0db8:85a3:0:0:8a2e:0370:7334", "method": "GET", "uri": "/picture.jpg", "headers": { "host": [ { "key": "Host", "value": "d111111abcdef8.cloudfront.net" } ], "user-agent": [ { "key": "User-Agent", "value": "curl/7.51.0" } ] } } } } ] }

Request events include the following values:

  • distributionId (read-only) – The ID of the distribution that's associated with the request.

  • clientIp (read-only) – IP address of the viewer that made the request. If the viewer used an HTTP proxy or a load balancer to send the request, the value is the IP address of the proxy or load balancer.

  • method (read-only) – HTTP method of the viewer request.

  • uri (read/write) – Relative path of the requested object. Note the following:

    • The new relative path must begin with a "/".

    • If the URI in the viewer request includes a query string, CloudFront doesn't include the query string in the uri value, so a function can't access it.

    • If a function changes the URI for a request, that changes the object that the viewer is requesting.

    • If a function changes the URI for a request, that doesn't change the cache behavior for the request or the origin that the request is forwarded to.

  • headers (read/write) – The headers in the request. The keys in the headers object are lowercase versions of the header names in the HTTP request. These lowercase keys give you case-insensitive access to the header values. Each header (for example, headers["accept"] or headers["host"]) is an array of key-value pairs, where key is the case-sensitive name of the header as it appears in an HTTP request and value is a header value. The number of elements in the array is the number of times a header is repeated in an HTTP request.

    For information about restrictions on header usage, see Header Restrictions.

Response Event

Here's the format of the event object that CloudFront passes to a Lambda function when the function is triggered by a CloudFront viewer response event or an origin response event.

Copy
{ "Records": [ { "cf": { "config": { "distributionId": "EDFDVBD6EXAMPLE" }, "request": { "clientIp": "2001:0db8:85a3:0:0:8a2e:0370:7334", "method": "GET", "uri": "/picture.jpg", "headers": { "host": [ { "key": "Host", "value": "d111111abcdef8.cloudfront.net" } ], "user-agent": [ { "key": "User-Agent", "value": "curl/7.18.1" } ] } }, "response": { "status": "200", "statusDescription": "OK", "headers": { "server": [ { "key": "Server", "value": "MyCustomOrigin" } ], "set-cookie": [ { "key": "Set-Cookie", "value": "theme=light" }, { "key": "Set-Cookie", "value": "sessionToken=abc123; Expires=Wed, 09 Jun 2021 10:18:14 GMT" } ] } } } } ] }

Response events include the following values:

  • distributionId (read-only) – The ID of the distribution that's associated with the request

  • request – One of the following:

    • Viewer response – The request that CloudFront received from the viewer and that might have been modified by the Lambda function that was triggered by a viewer request event

    • Origin response – The request that CloudFront forwarded to the origin and that might have been modified by the Lambda function that was triggered by an origin request event

    If the Lambda function modifies the request object, the changes are ignored.

  • response – One of the following:

    • Viewer response – The response that CloudFront will return to the viewer for viewer response events

    • Origin response – The response that CloudFront received from the origin for origin response events

  • status (read-only) – HTTP status code (such as 200) that CloudFront returns to the viewer.

  • statusDescription (read-only) – HTTP status description (such as OK) that CloudFront returns to the viewer.

  • headers (read/write) – The headers in the response. The keys in the headers object are lowercase versions of the header names in the HTTP response. These lowercase key gives you case-insensitive access to header values. Each header (for example, headers["set-cookie"] or headers["server"]) is an array of key-value pairs, where key is the case-sensitive name of the header as it appears in an HTTP response and value is a header value. The number of elements in the array is the number of times a header is repeated in an HTTP response.

    For information about restrictions on header usage, see Header Restrictions.