Navigation

HTTP Service

Use the HTTP service to integrate MongoDB Stitch apps with any third-party service that provides a REST API over HTTP, such as AWS Lambda. You can use the HTTP service to make outgoing HTTP requests to these services and to respond to incoming HTTP requests from them.

Set up HTTP Service to Make Outgoing HTTP Requests

Use the following procedures to set up an HTTP service to make outgoing HTTP requests.

A. Add HTTP Service to the MongoDB Stitch App

1

Go to the MongoDB Atlas project associated with your MongoDB Stitch application.

Tip

If you have not set up your cluster or set up your MongoDB Stitch application, see Getting Started.

  1. Log into Atlas.
  2. Navigate to the project associated with your MongoDB Stitch application.
  3. Select Stitch Apps in the left-hand nav panel.
  4. Select the application you wish to integrate with the HTTP Service. You will be redirected to the MongoDB Stitch console.
2

Add the HTTP service.

  1. In the MongoDB Stitch console, click Add service in the left-hand nav panel.
  2. Select HTTP.
  3. Enter a name for your HTTP service.
  4. Click Add service

B. Create Rules for the HTTP Service

For a HTTP service, you must specify rules to enable HTTP action or actions. The rules must evaluate to true for the action to be enabled. For more information on HTTP service rules, see HTTP Service Rules.

1

Add rules.

For the HTTP service:

  1. Click the Rules tab.
  2. Click Add Rule.
2

Specify the HTTP action(s) for which the rule applies.

In the Actions panel, set the switch to enabled for these action(s).

3

Specify the rule to apply for the selected actions.

In the When panel, enter the rule that determines when the selected actions are enabled.

Note

The rules must evaluate to true for the action to be enabled.

4

Click Save.

Repeat to add any additional rules.

Set up HTTP Service to Respond to Incoming HTTP Requests

Use the following procedure to set up an HTTP service to respond to incoming HTTP requests.

A. Add HTTP Service to the MongoDB Stitch App

1

Go to the MongoDB Atlas project associated with your MongoDB Stitch application.

Tip

If you have not set up your cluster or set up your MongoDB Stitch application, see Getting Started.

  1. Log into Atlas.
  2. Navigate to the project associated with your MongoDB Stitch application.
  3. Select Stitch Apps in the left-hand nav panel.
  4. Select the application you wish to integrate with the HTTP Service. You will be redirected to the MongoDB Stitch console.
2

Add the HTTP service.

  1. In the MongoDB Stitch console, click Add service in the left-hand nav panel.
  2. Select HTTP.
  3. Enter a name for your HTTP service.
  4. Click Add service

B. Create a MongoDB Stitch Incoming Webhook

A MongoDB Stitch Incoming Webhook is a callback URL used by third-party service providers to execute a function.

1

Click the Incoming Webhooks tab for your added HTTP service.

2

Click New Webhook.

3

Enter the following properties for the webhook.

Property Action
Name Enter the name for your new webhook.
Respond with Result Optional. Switch to enabled to send responses to URLs that invoke the incoming webhook.
Request Validation

Select the request validation method:

  • Verify Payload Signature to require that the incoming requests sign the message with a hexadecimal-encoded HMAC SHA-256 hash generated from the specified secret.
  • Require Secret as Query Param to require that the incoming requests include the specified secret as a query parameter.
Secret

Enter the secret associated with the selected Request Validation:

Output Type

Select the output type for the webhook function:

  • Select Array to return all documents from the function.
  • Select Single Document to return a single document from the function.
  • Select Boolean to return a boolean value indicating whether the function returned any output.
4

Specify the webhook function stage(s).

Use the function editor to write the webhook function code.

Example: The following webhook function inserts incoming data into a MongoDB collection.

exports = function(args) {
    var mdb = context.services.get("mongodb-atlas");
    var coll = mdb.database("test").collection("requestlogs");
    coll.insertOne({
        "body": args.body,
        "query": args.query,
    })
}

The args document is passed by the HTTP service and contains information from the request.

5

Click Create.

Upon successful creation of the webhook, its Webhook URL is displayed.

Examples of Request Validation Secret

You must specify a secret for the request validation you select.

Example: Signing Message Payload

Verify Payload Signature require that the incoming requests sign the message with a hexadecimal-encoded HMAC SHA-256 hash generated from the specified secret.

Sign message payloads by attaching a hexadecimal-encoded HMAC SHA-256 hash to HTTP requests. The message body must be a valid JSON document.

For example, the following Python code generates a hash of 828ee180512eaf8a6229eda7eea72323f68e9c0f0093b11a578b0544c5777862 from the following inputs:

  • Secret: ‘12345’
  • Message: ‘{“message”:”MESSAGE”}’
import hashlib;
import hmac;
message = bytes('{"message":"MESSAGE"}');
secret = bytes('12345');
hash = hmac.new(secret, message, hashlib.sha256);
print hash.hexdigest();

Attach the hash to the X-Stitch-Signature header, which has the following format:

X-Hook-Signature:sha256=<hex-encoded-hash>

The following curl statement demonstrates how to attach the generated hash to an HTTP request. Replace the URL with the URL for your MongoDB Stitch app’s incoming webhook and include include any other query parameters as appropriate:

curl -X POST -H "Content-Type: application/json" -H "X-Hook-Signature:sha256=828ee180512eaf8a6229eda7eea72323f68e9c0f0093b11a578b0544c5777862" \
 -d '{"message":"MESSAGE"}' https://stitch.mongodb.com/api/client/v1.0/app/hmac-test-vxdts/svc/http1/incomingWebhook/593ebc9d57e0fa4051f173e6

See hmac-examples for more examples of generating HMAC SHA-256 hashes. See Hash-based message authentication code for more information about HMAC.

Example: Secret Query Parameter

Require Secret as Query Param requires that the incoming requests include the specified secret as the value of the query parameter secret.

For example, given the following:

The following curl statement demonstrates how to include the secret query parameter in the request. Replace the URL with the URL for your MongoDB Stitch app’s incoming webhook and include include any other query parameters as appropriate:

curl -H "Content-Type: application/json" \
 -X POST "https://stitch.mongodb.com/api/client/v1.0/app/hmac-test-vxdts/svc/http1/incomingWebhook/593ebc9d57e0fa4051f173e6?secret=12345"
 -d { "message": "HELLO" }

Functions and HTTP Service

With MongoDB Stitch, you can define a sequence of actions to perform as a function of stages. For the HTTP service, MongoDB Stitch provides the following actions:

Action Description
httpService.get() Corresponds to the HTTP method GET.
httpService.post() Corresponds to the HTTP method POST.
httpService.delete() Corresponds to the HTTP method DELETE.
httpService.put() Corresponds to the HTTP method PUT.
httpService.patch() Corresponds to the HTTP method PATCH.
httpService.head() Corresponds to the HTTP method HEAD.