Modern applications often use multiple external services to handle complex use cases, such as messaging, analytics, and data management. You can connect to these services through MongoDB Realm by creating and configuring service interfaces.
Service interfaces specify the connection details for a specific external service and enable you to define the scope of that service's capabilities with custom service rules. Once you've configured an interface for a service, you can instantiate a service client that connects to the interface and exposes the service's actions as methods. You can also create incoming webhooks that enable external services to communicate directly with your Realm app over HTTP.
A service client is an object that connects to a service interface and enables you to call actions associated with the service. You can instantiate service clients in functions (using function context) as well as in your client application code.
For details on instantiating and using service clients, see Call a Service Action.
A service action is a method that handles a specific use case for a particular service, such as sending a text message with Twilio or putting an object to an AWS S3 bucket. Actions encapsulate implementation details like request authentication and HTTP methods behind semantic methods that are specific to each service.
MongoDB Realm blocks all service actions by default. You must configure a service rule that enables a particular action before you can call it.
For example, you could create a Twilio rule that only lets users send a text message from a specific phone number or an AWS rule that prevents users from putting objects to an S3 bucket that is not included in a list of approved buckets.
Expression variables are
variables that you can include in service rules to represent dynamic
information about your application and an action's execution. You can
configure service rules based on the authenticated user that called
an action (
%%user) and the arguments that they
%%args). You can also create complex
rules that call a Function (
evaluate based on the Function's return value.
An incoming webhook is a custom handler for events that originate from an external service, such as when someone opens a new pull request on GitHub or sends a text message to a Twilio phone number. Get started with incoming webhooks by configuring a service webhook.
Incoming webhooks consist of two primary components: the webhook URL and the webhook Function.
A URL that uniquely identifies the incoming webhook. External services can interact with the webhook by sending an HTTP request that matches the webhook's configuration to the webhook URL.
To use a webhook, provide the webhook URL to an external service's HTTP request handler, which may also be referred to as an outgoing webhook, callback URL, or similar.
If an incoming webhook requires a secret query parameter, make sure that you append the query parameter to webhook URL before you provide it to the external service.
|Webhook Function||A webhook function is a Realm Function that accepts an incoming HTTP request with data from the external service as its argument and optionally returns an HTTP response.|
|Configure Third-Party Services||Learn how to create a new external service interface.|
|Configure Service Webhooks||Learn how to configure and execute an incoming webhook to handle events in external services.|
|Configure Service Rules||Learn how to safely expose a service action for use in a function or client application.|
|Call a Service Action||Learn how to call a service action from a function or client application.|
|Twilio Service||Includes service configuration parameters, directions for adding a webhook to Twilio, and additional information about Twilio service actions.|
|HTTP Service||Includes additional information about HTTP service actions and webhooks.|
|AWS Service||Includes service configuration parameters, additional information about specifc AWS service actions, and generic directions for connecting to any AWS service.|
|GitHub Service||Includes service configuration parameters, directions for adding a webhook to GitHub, and guidance on validating incoming requests from GitHub.|
|Push Notifications||Includes service configuration parameters, arguments available in push notification rules, and directions for integrating push notifications into a mobile client.|
|Webhook Requests & Responses||Describes how to verify incoming requests, parse a request payload, and send a response in service webhook functions.|
|JSON Expressions||Describes how to construct and compose JSON expressions for use in service rules.|
|Expression Variables||Includes descriptions and usage examples for variable values in JSON expressions, including service rules.|