Skip to main content

HTTP Listener

The HTTP Listener is a Rush that listens for HTTP requests at a given URL and, when it receives a request, executes the defined handler.

How to configure​

For your HTTP Listener to work, you need to configure the handler parameter with the logic that will run when the HTTP Listener receives an HTTP request.

For more information about the other parameters, see the HTTP Listener reference.

Payload structure​

Inside the handler, you can access the following data using the data2-core-types@Reference component:

  • body: the request body
  • headers: the request headers
  • method: the request method
  • query: the request parameters

Client IP​

To get the real IP of whoever made the request (for example, to implement an allowlist), use the x-data2-client-ip header, accessible via headers.x-data2-client-ip.

The x-forwarded-for header is still available, but it isn't safe for authorization decisions: it includes anything the caller places before the hops added by the proxies. Use x-data2-client-ip when you need a trustworthy source.

Accessing request body values​

For example, if you make a POST request to your HTTP Listener with the following body:

{
  "fruit": "apple"
}

You can access this value using body.fruit in the reference parameter of the data2-core-types@Reference component.

Authentication​

To protect your HTTP Listener, you can add policies in the policies parameter of the HTTP Listener.

Versioning​

There are two ways to run an HTTP Listener:

  1. Hit the HTTP Listener's URL.
  2. Call the HTTP Listener's invoke method.

Versioning when accessed via URL​

In this case, the version used will be the one configured in the Builder. For more information, see the versioning section.

Versioning when called via the invoke method​

In this second case, the version used will be from the environment where the HTTP Listener's invoke was called.

Example:

  • HTTP Listener configured on version v2.
  • Application configured on version v1.

The Application has an Artboard with a button that calls the HTTP Listener via the invoke method. When the button is clicked, the HTTP Listener will be called on version v1, which is the same version as the Application.

Example​

In this example, we'll create an HTTP Listener that receives a POST request expecting a body with a fruit field, and returns a JSON response adding pie to the end of the fruit value. In other words, if the body is {"fruit": "apple"}, the response will be {"fruit": "apple pie"}.

Creating the HTTP Listener​

  • Double-click on the Builder background, select the Rush tab, then HTTP Listener.
  • Give your HTTP Listener a name, for example, FruitPieMaker.
  • Click Handler, then Actions and Add Item.
  • In the first action, we'll add a log to print the value of body.fruit to the Rush's execution logs. To do this:
    • Select LoggerService in Module.
    • Select log in Interaction.
    • In the message argument, click f() and select StringConcat. Click StringConcat, then click Portions to add the text you want.
    • Click Add Item and write something like Received fruit: .
    • Click Add Item again, click f(), and select Context Reference. Click Reference and enter body.fruit in the reference argument.
  • Check that the Enable Execution Logs and Should Log Request Body parameters are enabled.

It's good practice to test your HTTP Listener constantly to make sure it's working as expected. To do this, type { "fruit": "apple" } in the HTTP Listener's renderable Body field and click the Send button. In a few moments, you'll see the Rush's execution log in the Builder. Clicking the log lets you see information about the request, and in the Logs section, you should see a message with Received fruit: apple.

info

Logs are very useful while you're developing your Rush, and also for debugging problems that occur while the Rush is running. Use them often!

Notice that in the HTTP Listener's output, the body parameter is empty. This happened because we haven't configured what the handler should return. To do this:

  • Click Handler, then Actions and Add Item.
  • Click Actions and Add Item.
  • In the second action, we'll configure what to return. To do this:
    • Click f(), select object, and click to navigate.
    • Click the + next to the inspector's Object header to add a key to this object — in our case, fruit.
    • Click the f() next to fruit and select StringConcat. Click StringConcat, then click Portions to add the text you want.
    • Click Add Item twice.
    • In the second item, enter pie.
    • In the first item, click f() and select Context Reference. Click Reference and enter body.fruit in the reference argument.

Test the HTTP Listener again with the same request body, { "fruit": "apple" }, and you'll see that the output's body (body) now has the value { "fruit": "apple pie" }.

The HTTP Listener's URL is available in the HTTP Listener's renderable. You can click the button next to the URL to copy it.

HTTP Listener URL

Limitations​

The HTTP Listener does not yet support:

  • Custom domains.
  • Changing the HTTP Listener's URL.