HTTP Service [Deprecated]

On this page

Overview

Configuration Parameters
Service Actions
Incoming Webhooks
Configuration
Request Payload
Example Webhook Function

Atlas Device Sync, Atlas Edge Server, Data API, and HTTPS Endpoints are deprecated. Refer to the deprecation page for details.

Important

Third Party Services & Push Notifications Deprecation

Third party services and push notifications in App Services have been deprecated in favor of creating HTTP endpoints that use external dependencies in functions.

Webhooks have been renamed to HTTPS Endpoints with no change in behavior. You should migrate existing Webhooks.

Existing services will continue to work until September 30, 2025.

Because third party services and push notifications are now deprecated, they have been removed by default from the App Services UI. If you need to manage an existing third party service or push notification, you can add the configurations back to the UI by doing the following:

In the left navigation, under the Manage section, click App Settings.
Enable the toggle switch next to Temporarily Re-Enable 3rd Party Services, and then save your changes.

Overview

The Atlas App Services 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 App Services.

To send an outbound HTTP request, call one of the HTTP actions.
To handle incoming requests from an external service, configure an incoming webhook and provide it to the service, if possible. See the incoming webhooks section on this page for an example.

Configuration Parameters

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

/http_endpoints/<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 App Services 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

Note

Convert HTTP Webhooks to Endpoints

HTTP Service webhoooks are deprecated in favor of custom HTTPS endpoints. You can automatically migrate your existing webhooks to endpoints in one-click. To learn how, see Convert Webhooks to HTTPS Endpoints.

Configuration

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

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

http_endpoints/<Service Name>/<Webhook Name>/config.json

{
  "name": "<Webhook Name>",
  "can_evaluate": { <JSON Expression> },
  "run_as_authed_user": <Boolean>,
  "run_as_user_id": "<App Services User ID>",
  "run_as_user_id_script_source": "<Function Source Code>",
  "respond_result": <Boolean>,
  "fetch_custom_user_data": <Boolean>,
  "create_user_on_auth": <Boolean>,
  "options": {
    "httpMethod": "<HTTP Method>",
    "validationMethod": "<Webhook Validation Method>",
    "secret": "<Webhook Secret>"
  }
}

Configuration Value	Description
Webhook Name name	Required. The name of the webhook. Note Each incoming webhook in an HTTP service interface must have a unique name.
Respond With Result respond_result	Required. If `true`, App Services sends a response to the client that called the webhook. The response body will be the return value of the webhook function.
Run Webhook As run_as_user_id run_as_user_id_script_source	Optional. The id of the App Services 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 the system user, which has full access to MongoDB CRUD and Aggregation APIs and bypasses all rules and schema validation. 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 Atlas 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, App Services executes the webhook function as the system user that has full access to MongoDB CRUD and Aggregation APIs and bypasses all rules and schema validation.
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: Verify Payload Signature Require Secret as Query Param No validation. `VERIFY_PAYLOAD`: Verify Payload Signature `SECRET_AS_QUERY_PARAM`: Require Secret as Query Param `NO_VALIDATION`: No validation.
Secret options.secret	If Request Validation is enabled, this is the validation secret.

Request Payload

App Services 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:

{
   "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:

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

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

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.

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);
  })
};

Back

Configure Service Rules

http.get()