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. Servicios de aplicación te redirigirá 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 usuarios

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

Select the Webhook's HTTP Method

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

Especifica 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

Especificar 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

Guarda 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()
)

Save the Webhook

Debe guardar los cambios en su webhook antes de que surtan efecto. Para ello, haga clic en Save ya sea desde la ventana Settings, o desde el Function Editor.

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

Para definir un webhook entrante con realm-cli, necesitas una copia local de los archivos de configuración de tu 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>"

Add a Webhook Configuration Directory

Create a new subdirectory with the same name as the webhook in /http_endpoints/<service>/incoming_webhooks/:

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

Add a Webhook Configuration File

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 usuarios

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: {}
  }
}

To specify a webhook method, set the options.httpMethod field to the name of the method using all capital letters or "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.

Especifica 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.

To define an authorization expression, set the value of the can_evaluate field to the expression. If you do not specify an expression then App Services automatically authorizes all authenticated incoming requests.

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

Especificar 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.

You can configure a webhook's request authorization method in the options document of the webhook configuration. App Services supports the following request validation methods:

{
  "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

Add a file named source.js to the new webhook directory. The file should contain a valid function that will execute when the webhook is called.

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!" };
};

Implementa 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>"