Webhook Requests & Responses [Deprecated]

On this page

Overview

Request Validation Methods
Payload Signature Verification
Secret as a Query Parameter
Webhook Response Object

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

Depending on the service, incoming webhooks offer several ways to validate requests and customize the response that Atlas App Services sends back to the external service.

Request Validation Methods

To validate that a webhook request is coming from a trusted source, some external services require that incoming requests incorporate a secret string in one of several prescribed manners. Other services, like the HTTP service, allow you to optionally require request validation.

There are two type of Request Validation for webhooks: Payload Signature Verification and Secret as a Query Parameter.

HTTP/1.1 or greater is required when making requests.

Note

For maximum security, programmatically generate the secret string using a secure package such as the Python secrets module. Make sure that you do not publish the secret or include it in your version control system.

Payload Signature Verification

The Verify Payload Signature request validation option requires that incoming requests include a hexadecimal-encoded HMAC SHA-256 hash generated from the request body and secret string in the X-Hook-Signature header.

Example

Consider the following webhook request body and secret:

const body = { "message":"MESSAGE" }
const secret = 12345

The following Atlas Function generates the hash for this body and secret:

// Generate an HMAC request signature
exports = function(secret, body) {
  // secret = the secret validation string
  // body = the webhook request body
  return utils.crypto.hmac(EJSON.stringify(body), secret, "sha256", "hex");
}
// Returns: "828ee180512eaf8a6229eda7eea72323f68e9c0f0093b11a578b0544c5777862"

The hash value must be assigned to the X-Hook-Signature HTTP request header on every request:

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

To test that the request was properly signed, we could run the following curl command:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Hook-Signature:sha256=828ee180512eaf8a6229eda7eea72323f68e9c0f0093b11a578b0544c5777862" \
  -d '{"message":"MESSAGE"}' \
  <webhook URL>

Secret as a Query Parameter

The Require Secret as Query Param request validation option requires that incoming requests include the specified secret string as a query parameter appended to the end of the URL.

Example

Consider a webhook configured to use a secret value of 12345. All requests must be made to the webhook URL appended with the secret as a query parameter:

<webhook URL>?secret=12345

To test that requests to this URL are properly verified, we could run the following curl command:

curl -H "Content-Type: application/json" \
     -d '{ "message": "HELLO" }' \
     -X POST '<webhook URL>?secret=12345'

Webhook Response Object

App Services automatically passes a response object that represents the webhook's HTTP response as the second argument to webhook Function. The following table lists the available methods for modifying the response object:

Method

Arguments

Description

setStatusCode(code)

code integer

Set the HTTP response status code.

Example

response.setStatusCode(201);

setBody(body)

body string or BSON.Binary

Set the HTTP response body.

If body is a string, it will be encoded to BSON.Binary before being returned.

Example

response.setBody(
  "{'message': 'Hello, World!'}"
);

setHeader(name, value)

name string

value string

Set the HTTP response header specified by name to the value passed in the value argument. This overrides any other values that may have already been assigned to that header.

Example

response.setHeader(
  "Content-Type",
  "application/json"
);

addHeader(name, value)

name string

value string

Set the HTTP response header specified by name to the value passed in the value argument. Unlike setHeader, this does not override other values that have already been assigned to the header.

Example

response.addHeader(
  "Cache-Control",
  "max-age=600"
);
response.addHeader(
  "Cache-Control",
  "min-fresh=60"
)

Back

Call a Service Action

Configure Third-Party Services