Navigation

HTTP Endpoint Configuration Files

app/
└── http_endpoints/
└── <Service Name>/
├── config.json
└── <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.
http_endpoints/<Service Name>/<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>",
"respond_result": <Boolean>,
"fetch_custom_user_data": <Boolean>,
"create_user_on_auth": <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.
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>/<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