Service Webhooks

Some services in MongoDB Stitch support incoming webhooks. Webhooks enable your Stitch application to listen for HTTP requests from third-party services, and react to those requests by executing a function that you define in the Stitch admin console.

Some webhooks are specific to a particular service, such as webhooks for the GitHub service or Twilio service.

There are also webhooks for the HTTP service which can listen for and react to any HTTP request. These requests can be from standard services not supported directly by MongoDB Stitch, including custom services that you have built specifically for your application’s infrastructure.

In general, webhooks are useful when you are building a MongoDB Stitch application where events from third-party services need to trigger actions in your application.

Creating a Webhook

To create a new incoming webhook:

  1. Navigate to the Services page, which can be accessed from the navigation sidebar on the left-hand side of the MongoDB Stitch admin console.

  2. Click on the service for which you’d like to create a webhook.

  3. Click + Add Incoming Webhook.

  4. On the Settings tab that appears:

    1. Specify a Webhook Name.
    2. For Respond With Result, toggle whether or not you would like the HTTP response of the webhook to contain the result of the function executed by this webhook.
    3. The function that you’ll define for this webhook must be executed as a specific user when it is triggered. For the Run Webhook As setting, specify whether you want to run the webhook as a generic system user, a specific user ID, or as the result of a script that returns a specific user ID.
    4. If there are additional service-specific settings for the webhook, specify them in the remaining rows. Details about these service-specific settings are documented in each partner service’s documentation page.
  5. Click Save, which will create the webhook.

  6. You will be redirected to the Function Editor tab. This interface is the same as when you are creating normal MongoDB Stitch functions. For information about how to write functions, see Functions.

    Webhook functions differ from normal functions in that they are executed as the user specified in the Run Webhook As setting, and they always accept a payload argument. The contents of this payload are service-specific.

  7. To save changes made to the function, click the save icon in the editor.

Using a Webhook

For a third-party service to be able to use a MongoDB Stitch incoming webhook, that service must be provided with a URL to which it can make requests that trigger the webhook.

Once you’ve created a webhook in the Stitch console, you can retrieve the webhook URL by following these steps:

  1. Navigate to the Services page, which can be accessed from the navigation sidebar on the left-hand side of the MongoDB Stitch admin console.
  2. Click on the service that contains the webhook you are looking for.
  3. Click on the Settings tab.
  4. The first setting should be the Webhook URL, which contains the URL that you can copy and provide to the third-party service.

Some services may require additional steps to use or configure the webhook, so refer to that service’s specific documentation page for more information.

Parsing a Webhook Payload

The body field of the payload object passed to every webhook function is automatically encoded as BSON.Binary. To convert the content of the body field to an EJSON string, call the text() method on body:

const stringifiedBody = payload.body.text()

If the value of body is an EJSON string, it can be converted to a JSON document by using the EJSON.parse() method:

const stringifiedExtendedJson = payload.body.text()
const document = EJSON.parse(stringifiedExtendedJson)