Configure webhooks de serviço [obsoleto]

Configurar um novo webhook

Os webhooks recebidos têm como escopo serviços individuais. Você pode criar e gerenciar um webhook a partir de sua página de serviço associada na interface do usuário do App Services.

Para criar um webhook de entrada:

1. Clique em Services no menu de navegação esquerdo.

2. Clique no serviço ao qual você deseja adicionar um webhook de entrada.

3. Selecione a aba Incoming Webhooks para o serviço.

4. Clique em Add Incoming Webhook. O App Services redirecionará você para a tela Settings do novo webhook.

Dê um nome ao novo webhook

Insira um nome de identificação exclusivo para o webhook no campo Webhook Name. Esse nome deve ser diferente do usado em outros webhooks que você criou para o serviço.

Configurar autenticação de usuário

As Atlas Functions, incluindo webhooks, sempre são executadas no contexto de um usuário específico do aplicativo ou como usuário do sistema, o que ignora as regras. Para configurar o usuário de execução do webhook, especifique o tipo de autenticação que o App Services deve usar para o webhook.

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

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

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

clique para ampliar

Selecione o método HTTP do webhook

Você pode exigir que as solicitações recebidas usem um HTTP método específico ou você pode aceitar todos os HTTP métodos e tratar cada um individualmente na função webhook inspecionando a httpMethod propriedade no objeto context.request , como na função de exemplo a seguir:

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 a resposta do webhook

Você pode enviar uma resposta HTTP configurável para serviços externos que chamam o webhook.

Se você habilitar Respond With Result, o webhook responderá às solicitações recebidas com uma resposta HTTP 200 básica que inclui o valor de retorno da função webhook como seu campo body. Você pode configurar uma resposta HTTP personalizada na função de webhook usando o objeto response que o App Services passa automaticamente como o segundo argumento.

clique para ampliar

Especificar uma expressão de autorização

Você pode autorizar solicitações dinamicamente com base no conteúdo de cada solicitação definindo uma expressão Can Evaluate. O App Services avalia a expressão para cada solicitação recebida que o webhook recebe. Se você não especificar uma expressão, o App Services autorizará automaticamente todas as solicitações de entrada autenticadas.

A expressão pode expandir variáveis de expressão padrão, incluindo a expansão %%request.

clique para ampliar

Especifique o método de validação da solicitação

Para validar se uma solicitação de webhook foi enviada de uma fonte confiável, alguns serviços externos exigem que as solicitações recebidas incorporem uma string secreta em uma das várias maneiras prescritas. Outros serviços, como o serviço HTTP, permitem que você exija opcionalmente a validação da solicitação.

Se o webhook exigir validação da solicitação:

1. Selecione o método de validação de solicitação.

2. Insira uma string Secret para usar no processo de validação de solicitação.

clique para ampliar

Grave a função do webhook

Após configurar o webhook, tudo o que resta é escrever a função que executa quando alguém chama o webhook. O App Services passa automaticamente dois objetos como argumentos da função do webhook:

Você pode usar a seguinte função do webhook como base para seu próprio 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()
)

Salvar o webhook

Você deve salvar as alterações em seu webhook antes que elas entrem em vigor. Para fazer isso, clique em Save na tela Settings ou no Function Editor.

Obtenha a versão mais recente da sua aplicação

Para definir um webhook de entrada com realm-cli, você precisa de uma cópia local dos arquivos de configuração do seu aplicativo.

Para extrair uma cópia local da versão mais recente do seu aplicativo, execute o seguinte:

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

Adicione um diretório de configuração do webhook

Crie um novo subdiretório com o mesmo nome do webhook em /http_endpoints/<service>/incoming_webhooks/:

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

Adicionar um arquivo de configuração do webhook

Adicione um arquivo de configuração do webhook de entrada denominado config.json ao novo diretório do webhook.

O arquivo de configuração deve ter o seguinte 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>"
  }
}

Dê um nome ao novo webhook

Insira um nome para o webhook no campo name do arquivo de configuração. Esse nome deve ser diferente do usado em outros webhooks que você criou para o serviço.

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

Configurar autenticação de usuário

Especifique o tipo de autenticação que o App Services deve usar para o webhook. O App Services é compatível com os seguintes métodos de autenticação 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 o método HTTP do Webhook

Você pode exigir que as solicitações recebidas usem um método HTTP específico ou você pode aceitar todos os métodos HTTP e tratar cada um individualmente na função webhook inspecionando a httpMethod propriedade no objeto context.request , como na função de exemplo a seguir:

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 um método de webhook, defina o campo options.httpMethod como o nome do método usando todas as letras maiúsculas ou "ANY".

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

Configurar a resposta do webhook

Você pode enviar uma Resposta HTTP configurável a serviços externos que chamam o webhook. Para configurar o webhook para enviar uma resposta às solicitações recebidas, defina respond_result como true.

Se você habilitar Respond With Result, o webhook responderá às solicitações recebidas com uma resposta HTTP 200 básica que inclui o valor de retorno da função webhook como seu campo body. Você pode configurar uma resposta HTTP personalizada na função de webhook usando o objeto response que o App Services passa automaticamente como o segundo argumento.

Especificar uma expressão de autorização

Você pode autorizar solicitações dinamicamente com base no conteúdo de cada solicitação definindo uma expressão Can Evaluate . O App Services avalia a expressão para cada solicitação recebida que o webhook recebe. A expressão pode expandir variáveis de expressão padrão , incluindo a expansão %%request .

Para definir uma expressão de autorização , defina o valor do campo can_evaluate para a expressão. Se você não especificar uma expressão , o App Services autorizará automaticamente todas as solicitações de entrada autenticadas.

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

Especifique o método de validação da solicitação

Para validar se uma solicitação de webhook foi enviada de uma fonte confiável, alguns serviços externos exigem que as solicitações recebidas incorporem uma string secreta em uma das várias maneiras prescritas. Outros serviços, como o serviço HTTP, permitem que você exija opcionalmente a validação da solicitação.

Você pode configurar o método de autorização de solicitação de um webhook no documento options da configuração do webhook. O App Services oferece suporte aos seguintes métodos de validação de solicitação:

{
  "validationMethod": "NO_VALIDATION"
}

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

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

Adicione o código fonte da função do webhook

Adicione um arquivo denominado source.js ao novo diretório do webhook. O arquivo deve conter uma função válida que será executada quando o webhook for chamado.

O App Services passa automaticamente dois objetos como argumentos da função do webhook:

Você pode usar a seguinte função do webhook como base para seu próprio 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!" };
};

Distribua a configuração webhook de entrada

Depois de definir a preferência de leitura para o cluster no config.json, você poderá enviar a configuração para seu aplicativo remoto. O App Services CLI implementa imediatamente a atualização no push.

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