HTTP Endpoint Configuration Files
app/ └── http_endpoints/ ├── config.json └── [Deprecated] <Service Name>/ ├── config.json ├── rules/ │ └── <Rule Name>.json └── incoming_webhooks/ └── <Webhook Name>/ ├── config.json └── source.js
Endpoint Configuration
Define the configurations for your app's custom endpoints in http_endpoints/config.json
.
{ "route": "<Endpoint route name>", "http_method": "<HTTP method>", "function_name": "<Endpoint function name", "validation_method": "<Authorization scheme>", "respond_result": <boolean>, "fetch_custom_user_data": <boolean>, "create_user_on_auth": <boolean>, "disabled": <boolean> }
Field | Description |
---|---|
route string | The endpoint route. |
http_method string | The type of HTTP method that the
endpoint handles. Specify One of:
|
function_name string | The name of the function associated
with the endpoint. The function should use the endpoint
function signature. |
validation_method string | The endpoint authorization scheme used to validate incoming requests. One of:
|
respond_result boolean | If If |
fetch_custom_user_data boolean | If If |
create_user_on_auth boolean | If This setting is useful for apps that integrate with external authentication system through the Custom JWT authentication provider. If a request includes a valid JWT from the external system that doesn't correspond to a registered user, this creates a new user with the JWT as an identity. |
disabled boolean | Enables ( false ) or disables (true ) the endpoint. |
[Deprecated] HTTP Service Configuration
Deprecated legacy HTTP services are grouped into named services within
/http_endpoints
.
{ "name": "<Service Name>", "type": "http", "config": {} }
Field | Description |
---|---|
name String | The name of the HTTP endpoints service. This must be unique among all
HTTP endpoint services in the app and match the name of its containing
directory. |
type String | For HTTP endpoints, this value is always "http" . |
config String | Additional configuration options for the service. HTTP Endpoints
currently have no additional configuration options. |
[Deprecated] Service Action Rules
You define service action rules in the service's
rules/
sub-directory. Each rule maps to its own .json
configuration file
with the same name as the rule.
{ "name": "<Rule Name>", "actions": ["<Service Action Name>"], "when": { <JSON Rule Expression> } }
Field | Description |
---|---|
name String | The name of the service rule. The name may be at most 64
characters long and can only contain ASCII letters, numbers,
underscores, and hyphens. |
actions Array<String> | A list of HTTP actions that the rule
applies to. |
when Document | A rule expression that evaluates to true when
the rule applies to a given request. |
[Deprecated] Incoming Webhooks
Configuration
{ "name": "<Webhook Name>", "can_evaluate": { <JSON Expression> }, "run_as_authed_user": <Boolean>, "run_as_user_id": "<Realm User ID>", "run_as_user_id_script_source": "<Function Source Code>", "fetch_custom_user_data": <Boolean>, "create_user_on_auth": <Boolean>, "respond_result": <Boolean>, "options": { "httpMethod": "<HTTP Method>", "validationMethod": "<Webhook Validation Method>", "secret": "<Webhook Secret>" } }
Field | Description | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
name String | The name of the webhook. This must be unique among all webhooks in the
HTTP endpoints service and match the name of its containing directory. | |||||||||||||
can_evaluate JSON Expression (default: true ) | A JSON expression that evaluates to true if the
webhook is allowed to execute. Realm evaluates this
expression for every incoming request. | |||||||||||||
disable_arg_logs Boolean | If true , Realm omits the arguments provided to the webhook
from the function execution log entry. | |||||||||||||
run_as_authed_user Boolean | If Tip For an example of how to specify credentials, see Configure Service Webhooks [Deprecated]. | |||||||||||||
run_as_user_id String | The unique ID of a Realm User that
the function always executes as. Cannot be used with
run_as_user_id_script_source or run_as_authed_user . | |||||||||||||
run_as_user_id_script_source String | A stringified function that runs whenever the
webhook is called and returns the unique ID of a Realm
User that the function executes as. Cannot be used with
run_as_user_id or run_as_authed_user . | |||||||||||||
respond_result Boolean | If true , Realm includes the webhook function return value as
the body of the HTTP response it sends to the client that initiated the
webhook request. | |||||||||||||
fetch_custom_user_data Boolean | If This option is only available if | |||||||||||||
create_user_on_auth Boolean | If This option is only available if | |||||||||||||
options Document | A document that contains configuration options for the webhook.
|
Source Code
You define a webhook function's source code in a source.js
file within the
webhook directory. Each file must export the main function that runs whenever a
request calls the 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*, // Realm will include this return value as the response body. return { msg: "finished!" }; }