Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

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

accessing-headers page anchor

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:


_10
GET /example HTTP/1.1
_10
Host: test-4321.twil.io
_10
Authorization: 123abc
_10
Content-Type: application/json
_10
Content-Length: 23
_10
_10
{
_10
"body": "Ahoy!"
_10
}

You can access various headers in the following ways:


_16
exports.handler = (context, event, callback) => {
_16
// Access the `Authorization` header via dot notation
_16
const authHeader = event.request.headers.authorization;
_16
console.log(authHeader); // '123abc'
_16
_16
// Access the `Authorization` header via bracket notation
_16
const alsoTheAuthHeader = event.request.headers['authorization'];
_16
console.log(alsoTheAuthHeader); // '123abc'
_16
_16
// Access headers that include hyphens and other non-alphanumeric
_16
// characters with bracket notation
_16
const contentType = event.request.headers['content-type'];
_16
console.log(contentType); // 'application/json'
_16
_16
return callback();
_16
}

Accessing headers with multiple values

accessing-headers-with-multiple-values page anchor

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

For example, consider the following incoming request:


_10
GET /example HTTP/1.1
_10
Host: test-4321.twil.io
_10
Content-Type: application/json
_10
Cache-Control: no-cache
_10
Cache-Control: private
_10
Content-Length: 23
_10
_10
{
_10
"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:


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

(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]


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:


_10
GET /example HTTP/1.1
_10
Host: test-4321.twil.io
_10
Content-Type: application/json
_10
Cookie: Cookie_1=yummy; sessionToken=abc123
_10
Content-Length: 23
_10
_10
{
_10
"body": "Ahoy!"
_10
}

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


_15
exports.handler = (context, event, callback) => {
_15
// Access the `sessionToken` cookie via dot notation
_15
const sessionToken = event.request.cookies.sessionToken
_15
console.log(sessionToken); // 'abc123'
_15
_15
// Access the `sessionToken` cookie via bracket notation
_15
const alsoTheSessionToken = event.request.cookies['sessionToken'];
_15
console.log(alsoTheSessionToken); // 'abc123'
_15
_15
// The cookie header can contain multiple cookies
_15
const { cookies } = event.request;
_15
console.log(cookies); // { Cookie_1: 'yummy', sessionToken: 'abc123' }
_15
_15
return callback();
_15
}

Accessing cookies with multiple values

accessing-cookies-with-multiple-values page anchor

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:


_10
GET /example HTTP/1.1
_10
Host: test-4321.twil.io
_10
Content-Type: application/json
_10
Cookie: foo=bar; foo=baz
_10
Content-Length: 23
_10
_10
{
_10
"body": "Ahoy!"
_10
}

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


_10
exports.handler = (context, event, callback) => {
_10
// Access the cookie `foo`
_10
const foo = event.request.cookies.foo
_10
console.log(foo); // 'bar'
_10
_10
return callback();
_10
}

What determines the order of cookies when they share the same name? According to RFC-6265(link takes you to an external page):

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

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.


Rate this page: