Docs Menu

Convert Webhooks to HTTPS Endpoints

On this page

  • Overview
  • Automatically Convert Existing HTTP Webhooks
  • Manually Convert GitHub and Twilio Webhooks
  • GitHub Webhooks
  • Twilio Webhooks
  • Update Callback URLs in Client Apps & Services
  • Differences between Webhooks and Their Converted Endpoints

Atlas App Services's third-party service webhooks are deprecated in favor of custom HTTPS endpoints. HTTPS endpoints are functionally almost identical to webhooks but are now a first-class service.

This guide walks through converting your app's existing webhooks and updating external apps that call them. For new webhooks or callback URLs, you should define an HTTPS endpoint.

App Services can automatically convert any existing HTTP service webhooks in your app into HTTPS endpoints. This conversion is one-way which means that you cannot convert HTTPS endpoints back into webhooks. The conversion process does not delete the original webhooks so incoming webhook requests will continue to execute after the conversion.

To run the webhook to HTTPS endpoint conversion process for all webhooks in your application:

  1. Click HTTPS Endpoints in the left navigation menu of the Atlas App Services UI.
  2. Click the Convert button.
  3. Confirm that you want to run the conversion.
Convert all Endpoints in UI
Note

The converted HTTPS endpoints are independent from their source webhooks. If you choose to edit a webhook after running the conversion, you can run the conversion again with the "Convert & Override" option to propogate those changes to your new endpoints.

App Services cannot automatically convert GitHub and Twilio webhooks to HTTPS endpoints because they use deprecated client libraries. However, you can manually migrate webhooks from these services to new HTTPS endpoints.

To migrate a GitHub webhook to an HTTPS endpoint:

  1. Create a new HTTPS endpoint
  2. Copy the existing GitHub webhook code into the new endpoint's function
  3. Update your code to parse the incoming request body instead of using the pre-parsed GitHub payload.

    Before: A GitHub webhook with a pre-parsed payload
    exports = async function(payload, response) {
    // Webhooks only provide the parsed request body
    const { commits, pusher, repository } = payload;
    // ... your code here
    }
    After: An HTTPS endpoint that parses the GitHub payload
    exports = async function(payload, response) {
    // Endpoints pass an entire request payload, not just a parsed body
    const { commits, pusher, repository } = JSON.parse(payload.body.text());
    // ... your code here
    }

To migrate a Twilio webhook to an HTTPS endpoint:

  1. Create a new HTTPS endpoint
  2. Copy the existing Twilio webhook code into the new endpoint's function
  3. Update your code to parse the incoming request body instead of using the pre-parsed Twilio payload. If your webhook uses the built-in Twilio service client, update your code to use the twilio Node library instead.

    Before: A Twilio webhook with a pre-parsed payload
    exports = async function(payload, response) {
    // Webhooks only provide the parsed request body
    const { To, From, Body } = payload;
    // Webhooks could use a built-in Twilio client
    const twilio = context.services.get("twilio")
    twilio.send({
    To: From,
    From: context.values.get("TwilioPhoneNumber"),
    Body: `Message received!`
    })
    }
    After: An HTTPS endpoint that parses the Twilio payload
    exports = async function(payload, response) {
    // Endpoints pass an entire request payload, not just a parsed body
    const { To, From, Body } = JSON.parse(payload.body.text())
    // The endpoint should use `twilio` from npm instead of the built-in Twilio client
    const twilio = require('twilio')(
    // Your Account SID and Auth Token from https://www.twilio.com/console
    // Specify the same Twilio credentials as the service configuration
    context.values.get("TwilioAccountSID"),
    context.values.get("TwilioAuthToken"),
    )
    await twilio.messages.create({
    To: From,
    From: context.values.get("TwilioPhoneNumber"),
    Body: `Message received!`
    })
    }

HTTPS endpoints use a different URL scheme than service webhooks. You should update any apps or services that call your webhooks to instead call the converted HTTPS endpoint URL. Existing webhooks URLs will continue to accept requests and execute their associated functions after you've run the conversion. This means that you can gradually migrate to the new URLs without breaking existing workflows.

To migrate to the converted HTTPS endpoint URLs:

  1. Identify all client apps and services that call service webhooks
  2. For each app or service, modify the source code or configuration to use the new URLs.
  3. Monitor your app's logs for service webhook records to look for any active webhook callers that you missed.
  4. Once all clients are updated with the new URLs, delete the deprecated webhooks from your app.
Example

To migrate a service's integration from an App Services webhook to the converted HTTPS endpoint, modify the service's external configuration for outgoing webhook requests to point to the converted endpoint URL.

Deprecated HTTP Service Webhook URL
https://webhooks.mongodb-realm.com/api/client/v2.0/app/myapp-abcde/service/myHttpService/incoming_webhook/handleIncomingEvent
Converted HTTPS Endpoint URL
https://data.mongodb-api.com/app/myapp-abcde/endpoint/myHttpService/handleIncomingEvent

If you configured your converted HTTPS endpoint to use Respond with Result and the webhook function it's based on returns a value but does not invoke response.setBody(), the generated endpoint includes the function's return value as its response body. The webhook, in contrast, only returns a body specified by response.setBody().

Example
exports = function({ query, headers, body}, response){
response.setStatusCode(200);
return "Hello world";
};

The webhook for this function only responds with status code 200 without a body.

For the endpoint, if you enable Respond with Result, the endpoint responds with status code 200 and the body "Hello world". If you don't enable Respond with Result, the endpoint only responds with status code 200.

←  Replace Services with npm ModulesCall a Service Action [Deprecated] →
Give Feedback
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.