Navigation

HTTP Endpoint Configuration Files

app/
└── http_endpoints/
└── <Service Name>/
├── config.json
├── rules/
│ └── <Rule Name>.json
└── incoming_webhooks/
└── <Webhook Name>/
├── config.json
└── source.js

HTTP endpoints are grouped into named HTTP services. You define each HTTP service in its own subdirectory within /http_endpoints.

http_endpoints/<Service Name>/config.json
{
"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.

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.

http_endpoints/<Service Name>/rules/<Rule Name>.json
{
"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.
http_endpoints/<Service Name>/incoming_webhooks/<Webhook Name>/config.json
{
"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 true, the webhook function runs in the context of an existing application user specified by each incoming request. Incoming requests must include the user's authentication provider credentials in either the request body or the request headers.

Tip

For an example of how to specify credentials, see Configure Service Webhooks.

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 true, Realm queries the requesting user's custom user data and, if it exists, exposes the data as an object on the context.user.custom_data property.

This option is only available if run_as_authed_user is set to true.

create_user_on_auth
Boolean

If true, Realm automatically creates a new user based on the provided user credentials if they don't match an already existing user (e.g. no other user has the specified email address). The authentication provider that corresponds to the credentials must be enabled at the time of the request to create a new user.

This option is only available if run_as_authed_user is set to true.

options
Document

A document that contains configuration options for the webhook.

{
"httpMethod": "<HTTP Method>",
"validationMethod": "<Webhook Validation Method>",
"secret": "<Webhook Secret>"
}
Field
Description
httpMethod
String
The HTTP method type that the webhook accepts. Incoming webhook requests must use this method.
validationMethod
String

The name of the request validation method that the webhook uses.

Valid options:

  • "VERIFY_PAYLOAD"
  • "SECRET_AS_QUERY_PARAM"
  • "NO_VALIDATION"
secret
String
The secret value used to validate incoming webhook requests.

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.

http_endpoints/<Service Name>/incoming_webhooks/<Webhook Name>/source.js
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!" };
}
Give Feedback