Accessing headers and cookies

(information)

Info

Access to incoming headers and cookies is only available when your Function is running @twilio/runtime-handler version 1.2.0 or later. Consult the Runtime Handler guide to learn more about the latest version and how to update.

Accessing headers

Within a Function, headers are stored on the event.request.headers object and can be accessed by name in lowercase.

(warning)

Warning

The names of all headers are lowercased before being passed into your Function. Please reference headers with the correct casing to avoid errors.

For example, the key of the Content-Type header will be content-type.

For example, if the following request is received by your Function:

1GET /example HTTP/1.1
2Host: test-4321.twil.io
3Authorization: 123abc
4Content-Type: application/json
5Content-Length: 23
6
7{
8  "body": "Ahoy!"
9}

You can access various headers in the following ways:

1exports.handler = (context, event, callback) => {
2  // Access the `Authorization` header via dot notation
3  const authHeader = event.request.headers.authorization; 
4  console.log(authHeader); // '123abc'
5
6  // Access the `Authorization` header via bracket notation
7  const alsoTheAuthHeader = event.request.headers['authorization']; 
8  console.log(alsoTheAuthHeader); // '123abc'
9
10  // Access headers that include hyphens and other non-alphanumeric
11  // characters with bracket notation
12  const contentType = event.request.headers['content-type']; 
13  console.log(contentType); // 'application/json'
14
15  return callback();
16}

Accessing headers with multiple values

It is possible for a request to contain multiple values for a single header.

For example, consider the following incoming request:

1GET /example HTTP/1.1
2Host: test-4321.twil.io
3Content-Type: application/json
4Cache-Control: no-cache
5Cache-Control: private
6Content-Length: 23
7
8{
9  "body": "Ahoy!"
10}

Here, both no-cache and private have been assigned to the cache-control header. Since cache-control now has multiple values instead of a single value, it will return an array of strings when accessed:

1exports.handler = (context, event, callback) => {
2  // Access a multivalued header. In this case, `Cache-Control`
3  const cacheControl = event.request.headers['cache-control'];
4  console.log(cacheControl); // ['no-cache', 'private'];
5
6  return callback();
7}

(information)

Info

The order of multivalued headers in a request is preserved.

If you know for certain that the value of interest lies at a particular index of a header, you may access it directly. e.g. event.request.headers['cache-control'][1]

Accessing cookies

Cookies are stored on a separate event.request.cookies object, and can be accessed similarly.

(warning)

Warning

Cookie names are not forced to be lowercase like other headers and should be accessed using the casing in the request.

Given an incoming request like this to your Function:

1GET /example HTTP/1.1
2Host: test-4321.twil.io
3Content-Type: application/json
4Cookie: Cookie_1=yummy; sessionToken=abc123
5Content-Length: 23
6
7{
8  "body": "Ahoy!"
9}

The following code provides examples of how to access the provided cookie values:

1exports.handler = (context, event, callback) => {
2  // Access the `sessionToken` cookie via dot notation
3  const sessionToken = event.request.cookies.sessionToken
4  console.log(sessionToken); // 'abc123'
5
6  // Access the `sessionToken` cookie via bracket notation
7  const alsoTheSessionToken = event.request.cookies['sessionToken'];
8  console.log(alsoTheSessionToken); // 'abc123' 
9
10  // The cookie header can contain multiple cookies
11  const { cookies } = event.request;
12  console.log(cookies); // { Cookie_1: 'yummy', sessionToken: 'abc123' }
13
14  return callback();
15}

Accessing cookies with multiple values

Just like headers, is possible for a request to contain multiple cookies with the same name.

(warning)

Warning

In the case of multiple cookies with the same name, the Runtime Handler will only make the first value accessible. It will not convert that cookie into an array that contains all values.

For example, consider the following incoming request:

1GET /example HTTP/1.1
2Host: test-4321.twil.io
3Content-Type: application/json
4Cookie: foo=bar; foo=baz
5Content-Length: 23
6
7{
8  "body": "Ahoy!"
9}

If you were to access the cookie foo, you will notice that only the first value of 'bar' is returned instead of both:

1exports.handler = (context, event, callback) => {
2  // Access the cookie `foo`
3  const foo = event.request.cookies.foo
4  console.log(foo); // 'bar'
5
6  return callback();
7}

What determines the order of cookies when they share the same name? According to RFC-6265:

Cookies with longer paths are listed before cookies with shorter paths.
Among cookies that have equal-length path fields, cookies with earlier creation times are listed before cookies with later creation times.

What's next?

Now that you know how to access incoming headers and cookies, let's take a look at how you can set and modify headers on your Function responses.