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. See HTTP JavaScript Tutorial for an example integration with the Sendgrid email platform.

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

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 pipeline:

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

Specify the webhook pipeline stage(s).

For the displayed pipeline stage, hover over the stage to reveal the EDIT and DELETE buttons.

Click Edit and edit the following:

Field Action
Service Select the service for the stage.
Action

Select the action for the service. For a list of actions available, see Service Actions.

In the text box below the Action, enter the arguments to the specified action.

Note

You cannot directly reference the incoming request body and query parameters in the arguments specification.

Instead, to reference the incoming request body and/or query parameters in the stage, first define variables that reference the request body and/or query parameters in the Bind data to %%vars section. Then reference the variables in the arguments using the %%vars.<variable> expansion or reference the whole variables document with the expansion %%vars.

For example, if the specified is the built-in action literal, you would specify an argument that defines items:

{"items": ["%%vars"]}
Bind data to %%vars

Optional. Switch Bind data to %%vars to enabled to define variables to use as arguments to the action.

Note

You cannot directly reference the incoming request body and query parameters in the arguments specification.

Instead, to reference the incoming request body and/or query parameters in the stage, first define variables that reference the request body and/or query parameters in the Bind data to %%vars section. Then reference the variables in the arguments using the %%vars.<variable> expansion or reference the whole variables document with the expansion %%vars.

In the Bind data to %%vars text box, specify the variables.

For example, the following defines variables that references the query parameters fname, lname, status and the field message from the request body.

{
  "name": {
     "first": "%%args.query.fname",
     "last": "%%args.query.lname"
  },
  "status": "%%args.query.status",
  "message": "%%args.body.message"
}

You can reference these variables in the action arguments section as "%%vars.name", "%%vars.status", and "%%vars.message" or you can reference the whole variables document with the expansion %%vars.

Click Done. To add more stages to the pipeline, click Add Stage and repeat this step.

Example: The following incoming webhook pipeline consists of two stages.

Service Action Args Let (Bind data to %%vars)
built-in literal { "items": [ "%%vars" ] }
{
  "body": "%%args.body",
  "query": "%%args.query"
}
mongodb-atlas insert
{
  "database": "test",
  "collection": "requestlogs"
}
 
  • The first stage defines documents using the body and query from the request URL.
  • The second stage inserts these documents into the requestlogs collection in the test database.
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" }

Pipelines and HTTP Service

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

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

Note

A pipeline can consist of stages that use different MongoDB Stitch services.