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", "requestId": "MRVMF7KydIvxMWfJIglgwHQwZsbG2IhRJ07sn9AkKUFSHS9EXAMPLE==" }, "request": { "clientIp": "2001:0db8:85a3:0:0:8a2e:0370:7334", "method": "GET", "uri": "/picture.jpg", "querystring": "size=large", "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.

  • requestId (read-only, viewer request events only) – An encrypted string that uniquely identifies a request. The requestId value also appears in CloudFront access logs as the x-edge-request-id. For more information, see Access Logs and Web Distribution Log File Format.

  • 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 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.

  • querystring – The query string, if any, that CloudFront received in the viewer request. If the viewer request doesn't include a query string, the event structure still includes querystring with an empty value. For more information about query strings, see Configuring CloudFront to Cache Based on Query String Parameters.

  • 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 Headers.

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", "requestId": "xGN7KWpVEmB9Dp7ctcVFQC4E-nrcOcEKS3QyAez--06dV7TEXAMPLE==" }, "request": { "clientIp": "2001:0db8:85a3:0:0:8a2e:0370:7334", "method": "GET", "uri": "/picture.jpg", "querystring": "size=large", "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 values that appear in the corresponding request event. In addition, response events include the following values:

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

  • requestId (read-only, viewer response events only) – An encrypted string that uniquely identifies a request. The requestId value also appears in CloudFront access logs as the x-edge-request-id. For more information, see Access Logs and Web Distribution Log File Format.

  • 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 Headers.