Navigation

HTTP Service

On this page

Overview

The Stitch HTTP Service is a generic interface that enables you to communicate with any service that is available over HTTP, such as those that provide a REST API. This is useful when you need to use a service that does not have a custom service built-in to Stitch.

Configuration Parameters

You will need to provide values for the following parameters when you create an HTTP service interface:

copy
<Service Name>/config.json
{
  "name": "<Service Name>",
  "type": "http",
  "config": {}
}
Parameter Description

Service Name

config.name
 The name of this HTTP service interface. This must be unique from all other service interfaces in your application.

Service Actions

The HTTP service in MongoDB Stitch provides the following actions that you can call in functions and in the SDKs. Each action maps to a standard HTTP request method.

For instructions on using an HTTP service action, see Call a Service Action.

Note

You must enable a service action in a service rule before you can call it.

Action Description
http.get() Send an HTTP GET request.
http.post() Send an HTTP POST request.
http.put() Send an HTTP PUT request.
http.patch() Send an HTTP PATCH request.
http.delete() Send an HTTP DELETE request.
http.head() Send an HTTP HEAD request.

Incoming Webhooks

Configuration

You will need to provide values for the following parameters when you create an HTTP incoming webhook:

You will need to provide a configuration file of the following form when you create an HTTP incoming webhook:

copy 
{
  "name": <string>,
  "respond_result": <boolean>,
  "run_as_user_id": <string>,
  "run_as_user_id_script_source": <string>,
  "options": {
    "httpMethod": <string>,
    "secret": <string>,
    "validationMethod": <string>
  }
}
Configuration Value Description

Webhook Name

name

Required. The name of the webhook.

Note

Each incoming webhook in a Twilio service interface must have a unique name.

Respond With Result

respond_result

Required. If true, Stitch sends a response to the client that called the webhook. The response body will be the return value of the webhook function.

Note

If Twilio receives a webhook response, it will automatically send a text message containing the webhook response’s body to the phone number that sent the initial message.

Run Webhook As

run_as_user_id
run_as_user_id_script_source

Optional. The id of the Stitch user that executes the webhook function when the webhook is called.

There are three ways to configure the execution user:

  • System: The execution user is a system user that has full access to MongoDB CRUD and Aggregation APIs and is not affected by any rules, roles, or permissions.
  • User Id: You select a specific application user to execute the function.
  • Script: You define a function that returns the id of the execution user.

You can specify the user id directly in run_as_user_id or provide a stringified Stitch function that accepts the webhook payload and returns the user id in run_as_user_id_script_source. If you do not specify a specific user id or a function that resolves to a user id, Stitch executes the webhook function as a system user that has full access to MongoDB CRUD and Aggregation APIs and is not affected by any rules, roles, or permissions.

HTTP Method

options.httpMethod

The HTTP method that incoming webhook requests should use. You can configure a webhook to accept any method or specify a specific method. The following methods are supported:

  • GET
  • POST
  • PUT
  • PATCH
  • DELETE
  • HEAD
  • ANY

Request Validation

options.validationMethod

The request validation method incoming requests should use. The following validation types are supported:

Secret

options.secret
 If Request Validation is enabled, this is the validation secret.

Request Payload

Stitch automatically passes a payload document as the first argument to incoming webhook functions. In an HTTP Service incoming webhook the payload object represents an incoming HTTP request and has the following form:

copy 
{
   "query": <query parameters>,
   "headers": <request headers>,
   "body": <request body (BSON)>
}
Field Description
query

A document where each field corresponds to a query parameter that the external service included in the webhook URL.

Example

A request sent to a webhook URL with the query parameters someParameter=42&anotherParameter=hello would have the following query document:

copy 
"query": {
  "someParameter": 42,
  "anotherParameter": "hello"
}
headers

A document where each field corresponds to an HTTP header that the external service included in the webhook URL.

Example

A request sent to a webhook URL with a Content-Type: application/json header would have the following headers document:

copy 
"headers": {
  "Content-Type": ["application/json"]
}
body

A BSON.Binary object encoded from the request body. You can access the request body by serializing the binary object to a string and then parsing the string to EJSON:

copy 
const body = EJSON.parse(payload.body.text())

Example Webhook Function

The following webhook function inserts incoming data into a MongoDB collection and returns the insertedId in the response body.

copy 
exports = function(payload, response) {
  const mongodb = context.services.get("mongodb-atlas");
  const requestLogs = mongodb.db("test").collection("requestlogs");
  requestLogs.insertOne({
    body: EJSON.parse(payload.body.text()),
    query: payload.query
  }).then(result => {
    response.setStatusCode(201);
    response.setBody(result.insertedId);
  })
};
←   twilio.send() http.get()  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.