Configure Service Webhooks [Deprecated]

Set Up a New Webhook

Incoming webhooks are scoped to individual services. You can create and manage a webhook from its associated service page in the App Services UI.

To create an incoming webhook:

1. Click Services in the left navigation menu.

2. Click the Service for which you want to add an incoming webhook.

3. Select the Incoming Webhooks tab for the service.

4. Click Add Incoming Webhook. App Services will redirect you to the Settings screen for the new webhook.

Name the New Webhook

Enter a unique, identifying name for the webhook in the Webhook Name field. This name must be distinct from any other webhooks that you've created for the service.

Configure User Authentication

Atlas Functions, including webhooks, always execute in the context of a specific application user or as the system user, which bypasses rules. To configure the webhook's execution user, specify the type of authentication that App Services should use for the webhook.

{
  "email": "<User's Email Address>",
  "password": "<User's Password>"
}

{
  "api-key": "<User's API Key>"
}

{
  "jwtTokenString": "<User's JWT Token>"
}

click to enlarge

Select the Webhook's HTTP Method

You can require that incoming requests use a specific HTTP method or you can accept all HTTP methods and handle each one individually in the webhook function by inspecting the httpMethod property on the context.request object, as in the following example function:

exports = function(payload, response) {
  switch(context.request.httpMethod) {
    case "GET": { /* Handle GET requests */ }
    case "POST": { /* Handle POST requests */ }
    case "PUT": { /* Handle PUT requests */ }
    case "DELETE": { /* Handle DELETE requests */ }
    case "PATCH": { /* Handle PATCH requests */ }
    default: {}
  }
}

Configure the Webhook Response

You can send a configurable HTTP Response to external services that call the webhook.

If you enable Respond With Result, the webhook will respond to incoming requests with a basic HTTP 200 response that includes the webhook function return value as its body field. You can configure a custom HTTP response from within the webhook function using the response object that App Services automatically passes as the second argument.

click to enlarge

Specify an Authorization Expression

You can dynamically authorize requests based on the contents of each request by defining a Can Evaluate expression. App Services evaluates the expression for every incoming request that the webhook receives. If you do not specify an expression then App Services automatically authorizes all authenticated incoming requests.

The expression can expand standard expression variables, including the %%request expansion.

click to enlarge

Specify the Request Validation Method

To validate that a webhook request was sent 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.

If your webhook requires request validation:

1. Select the request validation method.

2. Enter a Secret string to use in the request validation process.

click to enlarge

Write the Webhook Function

Once you've configured the webhook, all that's left is to write the function that executes when someone calls the webhook. App Services automatically passes two objects as the webhook function's arguments:

You can use the following webhook function as a base for your own webhook:

exports = async function (payload, response) {
  // Convert the webhook body from BSON to an EJSON object
  const body = EJSON.parse(payload.body.text());
  // Execute application logic, such as working with MongoDB
  if (body.someField) {
    const mdb = context.services.get("mongodb-atlas");
    const requests = mdb.db("demo").collection("requests");
    const { insertedId } = await requests.insertOne({
      someField: body.someField,
    });
    // Respond with an affirmative result
    response.setStatusCode(200);
    response.setBody(`Successfully saved "someField" with _id: ${insertedId}.`);
  } else {
    // Respond with a malformed request error
    response.setStatusCode(400);
    response.setBody(`Could not find "someField" in the webhook request body.`);
  }
  // This return value does nothing because we already modified the response object.
  // If you do not modify the response object and you enable *Respond with Result*,
  // App Services will include this return value as the response body.
  return { msg: "finished!" };
};

exports(
  { body: "This document is the webhook payload" },
  new HTTPResponse()
)

Save the Webhook

You must save changes to your webhook before they take effect. To do so, click Save from either the Settings screen or the Function Editor.

Pull the Latest Version of Your App

To define an incoming webhook with realm-cli, you need a local copy of your application's configuration files.

To pull a local copy of the latest version of your app, run the following:

realm-cli pull --remote="<Your App ID>"

Add a Webhook Configuration Directory

Create a new subdirectory with the same name as the webhook in /http_endpoints/<service>/incoming_webhooks/:

mkdir -p http_endpoints/<service>/incoming_webhooks/<webhook name>

Add a Webhook Configuration File

Add an incoming webhook configuration file named config.json to the new webhook directory.

The configuration file should have the following form:

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

Name the New Webhook

Enter a name for the webhook in the configuration file's name field. This name must be distinct from any other webhooks that you've created for the service.

{
  "name": "<Unique Webhook Name>"
}

Configure User Authentication

Specify the type of authentication that App Services should use for the webhook. App Services supports the following webhook authentication methods:

{
  "run_as_authed_user": true,
  "run_as_user_id": "",
  "run_as_user_id_script_source": "",
}

{
  "email": "<User's Email Address>",
  "password": "<User's Password>"
}

{
  "api-key": "<User's API Key>"
}

{
  "jwtTokenString": "<User's JWT Token>"
}

{
  "run_as_authed_user": false,
  "run_as_user_id": "",
  "run_as_user_id_script_source": "",
}

{
  "run_as_authed_user": false,
  "run_as_user_id": "<App Services User ID>",
  "run_as_user_id_script_source": "",
}

{
  "run_as_authed_user": false,
  "run_as_user_id": "",
  "run_as_user_id_script_source": "<Stringified Function>",
}

Specify the Webhook's HTTP Method

You can require that incoming requests use a specific HTTP method or you can accept all HTTP methods and handle each one individually in the webhook function by inspecting the httpMethod property on the context.request object, as in the following example function:

exports = function(payload, response) {
  switch(context.request.httpMethod) {
    case "GET": { /* Handle GET requests */ }
    case "POST": { /* Handle POST requests */ }
    case "PUT": { /* Handle PUT requests */ }
    case "DELETE": { /* Handle DELETE requests */ }
    case "PATCH": { /* Handle PATCH requests */ }
    default: {}
  }
}

To specify a webhook method, set the options.httpMethod field to the name of the method using all capital letters or "ANY".

{
  "options": {
    "httpMethod": "POST"
  }
}

Configure the Webhook Response

You can send a configurable HTTP Response to external services that call the webhook. To configure the webhook to send a response to incoming requests, set respond_result to true.

If you enable Respond With Result, the webhook will respond to incoming requests with a basic HTTP 200 response that includes the webhook function return value as its body field. You can configure a custom HTTP response from within the webhook function using the response object that App Services automatically passes as the second argument.

Specify an Authorization Expression

You can dynamically authorize requests based on the contents of each request by defining a Can Evaluate expression. App Services evaluates the expression for every incoming request that the webhook receives. The expression can expand standard expression variables, including the %%request expansion.

To define an authorization expression, set the value of the can_evaluate field to the expression. If you do not specify an expression then App Services automatically authorizes all authenticated incoming requests.

{
    "%%request.remoteIPAddress": {
        "$nin": [
            "248.88.57.58",
            "19.241.23.116",
            "147.64.232.1"
        ]
    }
}

Specify the Request Validation Method

To validate that a webhook request was sent 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.

You can configure a webhook's request authorization method in the options document of the webhook configuration. App Services supports the following request validation methods:

{
  "validationMethod": "NO_VALIDATION"
}

{
  "validationMethod": "VERIFY_PAYLOAD",
  "secret": "<Secret Value>"
}

{
  "validationMethod": "SECRET_AS_QUERY_PARAM",
  "secret": "<Secret Value>"
}

Add the Webhook Function Source Code

Add a file named source.js to the new webhook directory. The file should contain a valid function that will execute when the webhook is called.

App Services automatically passes two objects as the webhook function's arguments:

You can use the following webhook function as a base for your own webhook:

exports = async function (payload, response) {
  // Convert the webhook body from BSON to an EJSON object
  const body = EJSON.parse(payload.body.text());
  // Execute application logic, such as working with MongoDB
  if (body.someField) {
    const mdb = context.services.get("mongodb-atlas");
    const requests = mdb.db("demo").collection("requests");
    const { insertedId } = await requests.insertOne({
      someField: body.someField,
    });
    // Respond with an affirmative result
    response.setStatusCode(200);
    response.setBody(`Successfully saved "someField" with _id: ${insertedId}.`);
  } else {
    // Respond with a malformed request error
    response.setStatusCode(400);
    response.setBody(`Could not find "someField" in the webhook request body.`);
  }
  // This return value does nothing because we already modified the response object.
  // If you do not modify the response object and you enable *Respond with Result*,
  // App Services will include this return value as the response body.
  return { msg: "finished!" };
};

Deploy the Incoming Webhook Configuration

Once you've set the read preference for the cluster in config.json, you can push the config to your remote app. App Services CLI immediately deploys the update on push.

realm-cli push --remote="<Your App ID>"