Configurar webhooks de servicio

Configurar un nuevo webhook

Los webhooks entrantes se limitan a servicios individuales. Puedes crear y administrar un webhook desde su página de servicio asociada en la interfaz de usuario de App Services.

Para crear un webhook entrante:

1. Haga clic en Services en el menú de navegación de la izquierda.

2. Haga clic en el servicio para el cual desea agregar un webhook entrante.

3. Seleccione la pestaña Incoming Webhooks para el servicio.

4. Haga clic en Add Incoming Webhook. App Services lo redireccionará a la pantalla Settings para el nuevo webhook.

Nombra el nuevo webhook

Introduzca un nombre único e identificativo para el webhook en el campo Webhook Name. Este nombre debe ser distinto al de cualquier otro webhook que haya creado para el servicio.

Configurar la autenticación de usuario

Las funciones de Atlas, incluidos los webhooks, siempre se ejecutan en el contexto de un usuario específico de la aplicación o como usuario del sistema, lo que omite las reglas. Para configurar el usuario de ejecución del webhook, especifique el tipo de autenticación que App Services debe usar para el webhook.

{
  "email": "<User's Email Address>",
  "password": "<User's Password>"
}

{
  "api-key": "<User's API Key>"
}

{
  "jwtTokenString": "<User's JWT Token>"
}

haga clic para ampliar

Seleccione el método HTTP del webhook

Puede exigir que las solicitudes entrantes utilicen un método específico Método HTTPo puede aceptar todos los métodos HTTP y manejar cada uno individualmente en la función webhook inspeccionando la httpMethod propiedad en el objeto context.request, como en la siguiente función de ejemplo:

exports = function(payload, response) {
  switch(context.request.httpMethod) {
    case "GET": { /* Handle GET requests */ }
    case "POST": { /* Handle POST requests */ }
    case "PUT": { /* Handle PUT requests */ }
    case "DELETE": { /* Handle DELETE requests */ }
    case "PATCH": { /* Handle PATCH requests */ }
    default: {}
  }
}

Configurar la respuesta del webhook

Puede enviar una respuesta HTTP configurable a servicios externos que llaman al webhook.

Si Respond With Result habilita, el webhook responderá a las solicitudes entrantes con una respuesta HTTP 200 básica que incluye el valor de retorno de la función del webhook como su body campo. Puede configurar una respuesta HTTP personalizada desde la función del webhook usando el response objeto que App Services pasa automáticamente como segundo argumento.

haga clic para ampliar

Especificar una expresión de autorización

Puedes autorizar solicitudes dinámicamente según el contenido de cada una definiendo una Can Evaluate expresión. App Services evalúa la expresión para cada solicitud entrante que recibe el webhook. Si no especificas una expresión, App Services autoriza automáticamente todas las solicitudes entrantes autenticadas.

La expresión puede expandir variables de expresión estándar, incluida la %%request expansión.

haga clic para ampliar

Especifique el método de validación de la solicitud

Para validar que una solicitud de webhook se envió desde una fuente confiable, algunos servicios externos requieren que las solicitudes entrantes incorporen una cadena secreta de una de varias maneras prescritas. Otros servicios, como el servicio HTTP, permiten solicitar la validación de la solicitud de forma opcional.

Si su webhook requiere validación de solicitud:

1. Seleccione el método de validación de la solicitud.

2. Introduce una string Secret para usar en el proceso de validación de la solicitud.

haga clic para ampliar

Escribe la función Webhook

Una vez configurado el webhook, solo queda escribir la función que se ejecuta al llamarlo. App Services pasa automáticamente dos objetos como argumentos de la función del webhook:

Puede utilizar la siguiente función de webhook como base para su propio 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*,
  // App Services will include this return value as the response body.
  return { msg: "finished!" };
};

exports(
  { body: "This document is the webhook payload" },
  new HTTPResponse()
)

Guardar el webhook

Debes guardar los cambios en tu webhook para que surtan efecto. Para ello, haz clic en Save desde la pantalla Settings o en Function Editor.

Obtenga la última versión de su aplicación

Para definir un webhook entrante con realm-cli, necesita una copia local de los archivos de configuración de su aplicación.

Para extraer una copia local de la última versión de su aplicación, ejecute lo siguiente:

realm-cli pull --remote="<Your App ID>"

Agregar un directorio de configuración de webhook

Cree un nuevo subdirectorio con el mismo nombre que el webhook en /http_endpoints/<service>/incoming_webhooks/:

mkdir -p http_endpoints/<service>/incoming_webhooks/<webhook name>

Agregar un archivo de configuración de webhook

Agregue un archivo de configuración de webhook config.json entrante llamado al nuevo directorio de webhook.

El archivo de configuración debe tener el siguiente formato:

{
  "name": "<Webhook Name>",
  "can_evaluate": { <JSON Expression> },
  "run_as_authed_user": <Boolean>,
  "run_as_user_id": "<App Services 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>"
  }
}

Nombra el nuevo webhook

Introduzca un nombre para el webhook en el campo name del archivo de configuración. Este nombre debe ser distinto al de cualquier otro webhook que haya creado para el servicio.

{
  "name": "<Unique Webhook Name>"
}

Configurar la autenticación de usuario

Especifique el tipo de autenticación que App Services debe usar para el webhook. App Services admite los siguientes métodos de autenticación de webhook:

{
  "run_as_authed_user": true,
  "run_as_user_id": "",
  "run_as_user_id_script_source": "",
}

{
  "email": "<User's Email Address>",
  "password": "<User's Password>"
}

{
  "api-key": "<User's API Key>"
}

{
  "jwtTokenString": "<User's JWT Token>"
}

{
  "run_as_authed_user": false,
  "run_as_user_id": "",
  "run_as_user_id_script_source": "",
}

{
  "run_as_authed_user": false,
  "run_as_user_id": "<App Services User ID>",
  "run_as_user_id_script_source": "",
}

{
  "run_as_authed_user": false,
  "run_as_user_id": "",
  "run_as_user_id_script_source": "<Stringified Function>",
}

Especifique el método HTTP del webhook

Puede requerir que las solicitudes entrantes utilicen un método HTTP específico o puede aceptar todos los métodos HTTP y manejar cada uno individualmente en la función webhook inspeccionando la httpMethod propiedad en el objeto context.request, como en la siguiente función de ejemplo:

exports = function(payload, response) {
  switch(context.request.httpMethod) {
    case "GET": { /* Handle GET requests */ }
    case "POST": { /* Handle POST requests */ }
    case "PUT": { /* Handle PUT requests */ }
    case "DELETE": { /* Handle DELETE requests */ }
    case "PATCH": { /* Handle PATCH requests */ }
    default: {}
  }
}

Para especificar un método webhook, configure el campo options.httpMethod con el nombre del método usando todas letras mayúsculas o "ANY".

{
  "options": {
    "httpMethod": "POST"
  }
}

Configurar la respuesta del webhook

Puede enviar una respuesta HTTP configurable a los servicios externos que llaman al webhook. Para configurar el webhook y que envíe una respuesta a las solicitudes entrantes,respond_result configure true en.

Si Respond With Result habilita, el webhook responderá a las solicitudes entrantes con una respuesta HTTP 200 básica que incluye el valor de retorno de la función del webhook como su body campo. Puede configurar una respuesta HTTP personalizada desde la función del webhook usando el response objeto que App Services pasa automáticamente como segundo argumento.

Especificar una expresión de autorización

Puede autorizar solicitudes dinámicamente según el contenido de cada solicitud al definir una Can Evaluate expresión. App Services evalúa la expresión para cada solicitud entrante que recibe el webhook. La expresión puede expandir variables de expresión estándar, incluida la expansión %%request.

Para definir una expresión de autorización, asigne el valor del campo can_evaluate a la expresión. Si no especifica ninguna expresión, App Services autoriza automáticamente todas las solicitudes entrantes autenticadas.

{
    "%%request.remoteIPAddress": {
        "$nin": [
            "248.88.57.58",
            "19.241.23.116",
            "147.64.232.1"
        ]
    }
}

Especifique el método de validación de la solicitud

Para validar que una solicitud de webhook se envió desde una fuente confiable, algunos servicios externos requieren que las solicitudes entrantes incorporen una cadena secreta de una de varias maneras prescritas. Otros servicios, como el servicio HTTP, permiten solicitar la validación de la solicitud de forma opcional.

Puede configurar el método de autorización de solicitudes de un webhook en el options documento de la configuración del webhook. App Services admite los siguientes métodos de validación de solicitudes:

{
  "validationMethod": "NO_VALIDATION"
}

{
  "validationMethod": "VERIFY_PAYLOAD",
  "secret": "<Secret Value>"
}

{
  "validationMethod": "SECRET_AS_QUERY_PARAM",
  "secret": "<Secret Value>"
}

Agregar el código fuente de la función Webhook

Agregue un archivo llamado source.js al nuevo directorio del webhook. El archivo debe contener una función válida que se ejecute al llamar al webhook.

App Services pasa automáticamente dos objetos como argumentos de la función webhook:

Puede utilizar la siguiente función de webhook como base para su propio 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*,
  // App Services will include this return value as the response body.
  return { msg: "finished!" };
};

Implementar la configuración del webhook entrante

Una vez que haya configurado la preferencia de lectura para el clúster en config.json, puede enviar la configuración a su aplicación remota. La CLI de App Services implementa la actualización inmediatamente al enviarla.

realm-cli push --remote="<Your App ID>"