Informações gerais e exemplos de uso do apanhador de Webhooks
Vamos ver, por exemplo, o retorno de um serviço de formulário:
Neste retorno (como em muitos formulários), temos alguns campos padrões, como ID de formulário e email.
Em outros casos, o usuário final criará retornos ao adicionar e nomear os campos que ele precisa no seu formulário.
Quanto aos campos padrões, não precisamos fazer o mapeamento (mapping); basta colocar manualmente, um por um.
Agora, para os “dinâmicos”, como os chamamos, precisamos utilizar o “apanhador do Webhook” para fazer um mapeamento automático dos campos que recebemos.
Em outras palavras, utilizamos o apanhador do Webhook quando o mapping para o gatilho do Webhook para uma resposta “definida” não é possível, mas mesmo assim precisamos criar alguns campos do trigger.
É possível criar vários apanhadores de Webhook e atrelar cada um deles a um trigger do tipo Webhook.
Quando o recurso é adicionado ao gatilho, o usuário final encontrará um apanhador de Webhook ao utilizar o serviço que você está adicionando. Ele poderá pegar os dados de teste repassados ao Webhook do serviço-fonte para a URL do Webhook e, depois, finalizar a criação da automação, incluindo os campos que acabou de “pegar” ou “mapear” do apanhador no seu gatilho.
Um apanhador de Webhook pode ser do tipo simples, que apanha absolutamente todas as variáveis que são enviadas para o Webhook. Para cada variável que chegar, um campo do gatilho será criado.
O outro tipo de apanhador de Webhook é o customizável. Este permite pegar os campos de um array ou um objeto específico.
Adicionalmente, se os dados chegam como um array de objetos, onde em cada objeto tem variáveis que definem seu nome e valor, você consegue criar os campos com nomes apontados no objeto.
Nome - é o nome interno do apanhador do Webhook. Ele aparece no decorrer da configuração do serviço de integração.
Apanhador do Webhook customizável - a marcação demonstra que o apanhador estará capturando somente um tipo específico de campo. É possível incluir os campos adicionais embaixo.
Caminho para a matriz de elementos - é apontado o mapping do array/objeto do qual estaremos recebendo campos.
Mapeamento dos nomes - é apontado o mapping para uma variável dentro do array de objetos, o qual contém o nome. Este nome será usado como o nome do campo.
Mapping de valores - é apontado o mapping para uma variável dentro de um array de objetos, no qual constará o valor que queremos entregar para o campo do gatilho.
Todos os campos, além do campo Nome, não são obrigatórios. Quanto mais campos estão preenchidos, mais preciso fica o apanhador do Webhook.
Considere que os dados vêm em JSON de forma simples:
Se, nesse caso, as chaves dos campos forem sempre diferentes, criamos um apanhador de Webhook simples, sem marcação “**apanhador do Webhook customizável**”. Este apanhador irá capturar todos os campos que contiverem as chaves em questão e criará os respectivos campos no gatilho. Os nomes destes campos criados serão iguais às chaves do JSON.
Veja outro exemplo considerando uma parte de campos “estática” e outra “dinâmica”, com o envio do seguinte objeto:
Nesse caso, marcamos “customizável” e, no campo Pathway to element array, inserimos o valor fields.
Desta forma, o gatilho terá três campos estáticos, e tudo que chegar dentro do objeto fields será dinâmico. Então, o apanhador do Webhooks estará “buscando” apenas os campos deste objeto. Além disso, a quantidade de campos criados será igual à quantidade de variáveis, onde o nome do campo será igual ao nome da chave da variável.
Outra possibilidade contempla o recebimento de um array de objetos estruturado e mais complexo, com nome e valor:
Nesse caso, marcamos o apanhador como “customizável”; colocamos o valor answers no campo Caminho para Matriz de Elementos; inserimos o valor title no campo Mapeamento de Nomes e adicionamos o valor value no campo Mapeamento dos Valores.
Desta forma, o gatilho terá três campos estáticos, e o apanhador do Webhook estará captando tudo que receber no array de objetos answers . Para cada objeto será criado um campo separado do gatilho, onde o nome será copiado do title e o campo estará enviando o valor recebido em value.
Assim estará finalizada a configuração do apanhador de Webhook. Agora você pode conectar o apanhador configurado ao gatilho do tipo Webhook.
{ "data": { "utm_campaign": null, "fieldsData": [ { "field_label": "Text field", "field_value": "123123", "field_type": "text", "field_key": "", "field_id": "dmform-00" }, { "field_label": "Drop Field", "field_value": "Drop 3", "field_type": "dropdown", "field_key": "", "field_id": "dmform-01" }, { "field_label": "New Field", "field_value": "213123", "field_type": "text", "field_key": "", "field_id": "dmform-03" }, { "field_label": "Title", "field_value": "Contact Us", "field_type": "form_title", "field_key": "", "field_id": null } ], "recipients": [ "suporte@albato.com.br" ], "emailSubject": "Form Message", "emailSender": "" }, "source": null, "resource_data": { "site_name": "2397615eedd94c4dad7d7ba745b78e5d" }, "event_timestamp": 1635800515075, "event_type": "CONTACT_FORM_SENT_V2"}Neste retorno (como em muitos formulários), temos alguns campos padrões, como ID de formulário e email.
Em outros casos, o usuário final criará retornos ao adicionar e nomear os campos que ele precisa no seu formulário.
Quanto aos campos padrões, não precisamos fazer o mapeamento (mapping); basta colocar manualmente, um por um.
Agora, para os “dinâmicos”, como os chamamos, precisamos utilizar o “apanhador do Webhook” para fazer um mapeamento automático dos campos que recebemos.
Em outras palavras, utilizamos o apanhador do Webhook quando o mapping para o gatilho do Webhook para uma resposta “definida” não é possível, mas mesmo assim precisamos criar alguns campos do trigger.
É possível criar vários apanhadores de Webhook e atrelar cada um deles a um trigger do tipo Webhook.
Quando o recurso é adicionado ao gatilho, o usuário final encontrará um apanhador de Webhook ao utilizar o serviço que você está adicionando. Ele poderá pegar os dados de teste repassados ao Webhook do serviço-fonte para a URL do Webhook e, depois, finalizar a criação da automação, incluindo os campos que acabou de “pegar” ou “mapear” do apanhador no seu gatilho.
Um apanhador de Webhook pode ser do tipo simples, que apanha absolutamente todas as variáveis que são enviadas para o Webhook. Para cada variável que chegar, um campo do gatilho será criado.
O outro tipo de apanhador de Webhook é o customizável. Este permite pegar os campos de um array ou um objeto específico.
Adicionalmente, se os dados chegam como um array de objetos, onde em cada objeto tem variáveis que definem seu nome e valor, você consegue criar os campos com nomes apontados no objeto.
Campos do apanhador do Webhook
Nome - é o nome interno do apanhador do Webhook. Ele aparece no decorrer da configuração do serviço de integração.
Apanhador do Webhook customizável - a marcação demonstra que o apanhador estará capturando somente um tipo específico de campo. É possível incluir os campos adicionais embaixo.
Caminho para a matriz de elementos - é apontado o mapping do array/objeto do qual estaremos recebendo campos.
Mapeamento dos nomes - é apontado o mapping para uma variável dentro do array de objetos, o qual contém o nome. Este nome será usado como o nome do campo.
Mapping de valores - é apontado o mapping para uma variável dentro de um array de objetos, no qual constará o valor que queremos entregar para o campo do gatilho.
Todos os campos, além do campo Nome, não são obrigatórios. Quanto mais campos estão preenchidos, mais preciso fica o apanhador do Webhook.
Exemplos de uso
Considere que os dados vêm em JSON de forma simples:
{"name":"name","phone":"5521988888123","email":"email"}Se, nesse caso, as chaves dos campos forem sempre diferentes, criamos um apanhador de Webhook simples, sem marcação “**apanhador do Webhook customizável**”. Este apanhador irá capturar todos os campos que contiverem as chaves em questão e criará os respectivos campos no gatilho. Os nomes destes campos criados serão iguais às chaves do JSON.
Veja outro exemplo considerando uma parte de campos “estática” e outra “dinâmica”, com o envio do seguinte objeto:
{"name":"name","phone":"5521988888123","email":"email","fields":{ "field1":"value1", "field2":"value2" }}Nesse caso, marcamos “customizável” e, no campo Pathway to element array, inserimos o valor fields.
Desta forma, o gatilho terá três campos estáticos, e tudo que chegar dentro do objeto fields será dinâmico. Então, o apanhador do Webhooks estará “buscando” apenas os campos deste objeto. Além disso, a quantidade de campos criados será igual à quantidade de variáveis, onde o nome do campo será igual ao nome da chave da variável.
Outra possibilidade contempla o recebimento de um array de objetos estruturado e mais complexo, com nome e valor:
{"name":"name","phone":"5521988888123","email":"email","answers": [ { "title":"Titulo Exemplo 1", "value":"Valor exemplo 1" }, { "title":"Titulo exempl 2", "value":"Valor exemplo 2" }]}Nesse caso, marcamos o apanhador como “customizável”; colocamos o valor answers no campo Caminho para Matriz de Elementos; inserimos o valor title no campo Mapeamento de Nomes e adicionamos o valor value no campo Mapeamento dos Valores.
Desta forma, o gatilho terá três campos estáticos, e o apanhador do Webhook estará captando tudo que receber no array de objetos answers . Para cada objeto será criado um campo separado do gatilho, onde o nome será copiado do title e o campo estará enviando o valor recebido em value.
Assim estará finalizada a configuração do apanhador de Webhook. Agora você pode conectar o apanhador configurado ao gatilho do tipo Webhook.
Atualizado em: 08/12/2022
Obrigado!