Webhooks em Quoti Databases

Ao adicionar, remover, editar ou fazer qualquer operação em uma tabela do Quoti Databases, uma série de processos internos ocorrem na plataforma. Um deles é a chamada de Webhooks.

Webhooks no Quoti Databases tem as seguintes características:

• Os webhooks são chamados a partir de eventos de operações no banco de dados.
• Podem ter caráter bloqueante. Isso é: pode bloquear uma operação como de escrita, por exemplo.
• Podem modificar o dado que estaria sendo criado ou editado, trazendo a possibilidade de tratar campos, por exemplo.
• Podem ser configurados para serem disparados em condições específicas, como apenas quando uma coluna específica recebe algum valor específico.

Eventos

Aqui está uma lista de possíveis eventos que o Quoti pode detectar para chamar um webhook

• Eventos relacionado a criação de registros: - beforeCreate - Chamado antes de um registro ser criado - beforeBulkCreate - Chamado antes de ser criado vários registros (em lote) - afterCreate - Chamado após a criação de qualquer registro - afterBulkCreate - Chamado após a criação de vários registros (em lote)
• Eventos relacionados a atualização de registros: - beforeUpdate - Chamado antes de um registro ser atualizado - beforeBulkUpdate - Chamado antes de vários registros serem atualizados (em lote) - afterUpdate - Chamado depois de um registro ser atualizado - afterBulkUpdate - Chamado depois de vários registros serem atualizados (em lote)
• Eventos relacionados a deleção de registros: - beforeDestroy - Chamado antes de um registro ser apagado - beforeBulkDestroy - Chamado antes de vários registros serem apagados (em lote) - afterDestroy - Chamado depois de um registro ser apagado - afterBulkDestroy - Chamado depois de vários registros serem apagados (em lote)
• Eventos relacionados a listagem de registros: - beforeFind - Chamado antes de uma solicitação de listagem de registros

Cadastrando Webhooks

A página de gestão de hooks do seu ambiente está disponível em https://quoti.cloud/seuambiente/hooks

Você pode cadastrar um novo webhook através do botão “+ Novo”

1. Tipo de hook - Para webhooks de Quoti Databases, você deve selecionar sempre o tipo “table”.
2. Nome do recurso - Aqui você deve escolher o nome da sua tabela que acionará os hooks.
3. Handler - Este campo recebe um JSON, que deve conter em seu corpo as propriedades url e type. Respectivamente, guardam o link que será chamado e o tipo de requisição
4. Eventos - Este campo pode receber múltiplos eventos, os quais servirão como gatilhos para acionar o webhook.
5. Condições - Campo opcional que define condições específicas no qual a plataforma deve considerar para disparar o webhook. Este campo deve receber um JSON no formato documentado neste link.
6. Configurações - Campo opcional que define configurações avançadas de um webhook. O formato esperado é JSON e suas possível propriedades são as seguintes: - returnBeforeData - Campo booleano (com valor true ou false) que determina se a plataforma deve incluir a informação de ‘beforeData’ no corpo da chamada do webhook para eventos de atualização. ‘beforeData’ representa os dados na tabela antes da finalização da edição do registro em andamento. - returnAfterData - Campo booleano (com valor true ou false) que determina se a plataforma deve incluir a informação de ‘afterData’ no corpo da chamada do webhook para eventos de atualização. ‘afterData’ representa os dados na tabela após a finalização da edição do registro que acabou de ser feita - neste caso, apenas nos eventos de ‘afterUpdate’ este campo estará com os dados definidos.

Operadores disponíveis

Tipo	Operador	Descrição
Booleano	all, any, not	Controlam a lógica de múltiplas condições
String/Número	equal, notEqual	Igualdade ou diferença exata (=== / !==)
Numérico	lessThan, lessThanInclusive, greaterThan, greaterThanInclusive	Comparações numéricas diretas
Array	in, notIn, contains, doesNotContain	Verifica se um valor está em um array (in/notIn) ou se um array contém um valor (contains/doesNotContain)

Operadores que suportam value como lista: in, notIn, contains, doesNotContain

ℹ️ Para detalhes completos sobre sintaxe, operadores e exemplos de uso, consulte a documentação da biblioteca.

Operadores Adicionais

Básicos

Operador	Descrição
isEmpty	Verifica se o valor é null ou undefined
isNotEmpty	Verifica se o valor não é null e não é undefined

String

Operador	Descrição
contains	Verifica se uma string contém outra string
startsWith	Verifica se uma string começa com outra string
endsWith	Verifica se uma string termina com outra string
matches	Verifica se uma string corresponde a um padrão regex

Array

Operador	Descrição
containsAny	Verifica se um array contém qualquer um dos valores especificados
containsAll	Verifica se um array contém todos os valores especificados
hasLength	Verifica se um array tem exatamente o comprimento especificado
isEmptyArray	Verifica se um array está vazio
isNotEmptyArray	Verifica se um array não está vazio

Número

Operador	Descrição
isInRange	Verifica se um número está dentro de um intervalo (inclusive)
isNumber	Verifica se um valor é um número
isPositive	Verifica se um número é positivo (maior que 0)
isNegative	Verifica se um número é negativo (menor que 0)

Data

Operador	Descrição
isAfter	Verifica se uma data é posterior a outra data
isBefore	Verifica se uma data é anterior a outra data
isSameDay	Verifica se uma data é o mesmo dia que outra data
isDateInRange	Verifica se uma data está dentro de um intervalo

Tipo

Operador	Descrição
isString	Verifica se um valor é uma string
isBoolean	Verifica se um valor é um booleano
isArray	Verifica se um valor é um array
isObject	Verifica se um valor é um objeto (não null, não array)

Objeto

Operador	Descrição
hasProperty	Verifica se um objeto tem uma propriedade específica
hasProperties	Verifica se um objeto tem todas as propriedades especificadas

Exemplos de Webhooks

Exemplo 1 – Webhook somente para categorias específicas

Dispara apenas se o categoryId enviado estiver em uma lista predefinida (ex: manutenção de ATM e validadores):

Configurações:

{
  "asyncHook": true,
  "returnAfterData": false,
  "returnBeforeData": false
}

Condições:

{
  "all": [
    {
      "fact": "requestData",
      "path": "$.body.categoryId",
      "value": [
        100004, 100015, 100016, 100019, 100031,
        100032, 100033, 100034, 100035, 100036,
        100037, 100038, 100039, 100040, 100041
      ],
      "operator": "in",
      "description": "Apenas ticket manutenção de ATM e validadores"
    }
  ]
}

---

Exemplo 2 – Webhook ignorando chats e CCO

Executa o webhook apenas quando o (ticketTypeId) não corresponder a determinados valores específicos:

💡 Como mostrado na imagem abaixo, o conteúdo retornado na chave after deve ser referenciado como dataAfterEvent na condição. Logo, o fact correto a ser utilizado será "dataAfterEvent"

Configurações:

{
  "attributes": ["ticketTypeId"],
  "returnAfterData": true,
  "returnBeforeData": false
}

Condições:

{
  "all": [
    {
      "fact": "dataAfterEvent",
      "path": "$.ticketTypeId",
      "value": [3, 11],
      "operator": "notIn",
      "description": "Chamados diferentes de chats e CCO"
    }
  ]
}

---

Exemplo 3 – Webhook só dispara se status não for nulo

Verifica se a propriedade status existe e contém pelo menos 1 item:

Condições:

{
  "all": [
    {
      "fact": "requestData",
      "path": "$.body.status.length",
      "value": 1,
      "operator": "greaterThanInclusive",
      "description": "Status diferente de nulo"
    }
  ]
}

Caso de teste

Vamos criar um webhook de afterCreate em uma tabela e ver como ele é chamado!

Após a criação, é necessário definir o “Status do webhook” como “Ativo” para que a plataforma o considere.

Agora que temos nosso webhook definido, vamos criar um dado aleatório na tabela relacionada e verificar a chamada de webhook que a plataforma fez.

Aqui está o corpo da chamada HTTP feita pela plataforma:

O conteúdo de toda chamada contém:

• Parâmetro user - Onde vem uma cópia da instancia do usuário que está fazendo a operação, incluindo grupos e permissões
• Parâmetro resourceType - Contém o valor do campo “Tipo de hook” definido na hora da criação do webhook. No caso de webhooks de Quoti Databases, esse valor sempre será “table”.
• Parâmetro resourceName - Contém o nome da tabela onde o evento se originou.
• Parâmetro event - Contém o nome do evento que está sendo disparado
• Parâmetro data - Objeto que contém os dados que estão sendo criados ou atualizados ou apagados, de acordo com o evento. Caso o hook tenha as configuração. "returnBeforeData” e “returnAfterData” habilitadas, os dados relacionados também serão retornados dentro deste objeto.