Todas as coleções
Integrações e fórmulas externas
Como utilizar os Webhooks do Ploomes
Como utilizar os Webhooks do Ploomes
Lucca Leão von Simson avatar
Escrito por Lucca Leão von Simson
Atualizado há mais de uma semana

Ploomes conta com a funcionalidade de Webhooks. Para contextualizar, um Webhook é um meio pelo qual um sistema fornecer informações em tempo real para outras aplicações ou serviços. Por exemplo: sempre que uma venda for cadastrada no Ploomes, enviar os dados para um ERP.

Como habilitar

Para habilitar os Webhooks na sua conta, é necessário fazer uso da API do Ploomes. O primeiro passo é registrar um endpoint para receber dados quando uma determinada ação no Ploomes acontecer. Um endpoint é simplesmente um endereço acessível por HTTP, pode ser um Webservice ou uma API própria ou de terceiros. Uma ação pode ser, por exemplo:

  • Cadastrar um cliente

  • Atualizar uma proposta

  • Finalizar uma tarefa

  • Excluir um Lead

Para realizar o registro, basta fazer um POST no seguinte endereço:
​https://api2.ploomes.com/Webhooks

É necessário utilizar sua chave de integração no Header da requisição, na forma de um parâmetro 'User-Key' e o corpo da requisição deve contar os seguintes atributos:
{
"EntityId": 1,
"ActionId": 2,
"CallbackUrl": "sua_url_de_recebimento",
"ValidationKey": "1234"
}

O exemplo acima vai fazer com que dados sejam disparados para um determinado endereço sempre que um Cliente for atualizado.

Parâmetros

Abaixo a explicação para cada atributo:

  • ActionId: o ID da ação. Uma ação pode ser, por exemplo, criação, deleção, atualização ou ações específicas para algumas entidades, como no caso de Negócios que podem ser Ganhos, Perdidos e Reabertos e Tarefas que podem ser finalizadas. Para saber quais as ações disponíveis, basta dar um GET no seguinte endereço (sempre se lembre da chave do usuário no Header):
    ​https://public-api2.ploomes.com/Webhooks@Actions

  • CallbackUrl: a URL (endereço WEB) que receberá os dados enviados pelos Webhooks do Ploomes

  • ValidationKey: uma chave que pode ser criada (inventada) e usada no endereço que vai receber os dados do Ploomes. Com ela, é possível validar se as requisições estão sendo enviadas pelo Ploomes mesmo e rejeitar as demais, no caso de alguém descobrir seu serviço e tentar algum ataque, por exemplo.

Na mensagem enviada, a chave de validação (ValidationKey) estará no Header com o nome X-Ploomes-Validation-Key

Corpo do Payload (exemplo)

______________________________________________________

Body:
{
"Action": "Update",
"Entity": "Contacts",
"AccountId": 57,
"ActionUserId": 116,

"Old":
{
"OtherProperties": {
"contact_check": false //CAMPOS CUSTOMIZÁVEIS DA CONTA
},
"Phones": [
{
"PhoneNumber": "(11) 3842-6673",
"TypeId": 1,
"CountryId": 76
}
],
"Tags": [
{
"TagId": 290
}
],
"Id": 2630362,
"LegalName": "Ploomes",
},

"New":
{
"OtherProperties": {
"contact_check": true
},
"Phones": [
{
"PhoneNumber": "(11) 4380-7749",
"TypeId": 1,
"CountryId": 76
}
],
"Tags": [
{
"TagId": 287
}
],
"Id": 2630362,
"LegalName": "Ploomes Sistemas Empresariais",
}
}
______________________________________________________

Análise do payload

"Action": "Update", --> Atualização
"Entity": "Contacts", --> de Contato
"AccountId": 57, --> ID da conta Ploomes
"ActionUserId": 116, --> ID do usuário que gerou a ação (atualizou o contato)

Old --> Detalhes de como eram os campos ANTES da atualização - somente os campos alterados são retornados. Pode ser NULL caso seja uma Criação.
​New --> Detalhes dos valores dos campos DEPOIS da atualização.

Com o atributo ActionUserId e os objetos OLD e NEW é possível identificar os valores antes e depois de cada alteração e com isso fazer tratativas específicas para cada caso.

Exemplo de caso de uso: Se um usuário (ActionUserId) da equipe financeira editar o campo 'Análise de crédito concluída' de Falso para Verdadeiro, enviar um e-mail para o responsável pelo Negócio informando que a análise foi concluída e agora o processo comercial pode prosseguir.


Para acessar obter acesso à API do Ploomes, acesse o link abaixo:
​Como obter acesso à API do Ploomes


​

Caso tenha dúvidas sobre a utilização dos Webhooks ou precisar de informações adicionais, nossa equipe de suporte estará sempre à disposição para ajudar.

Respondeu à sua pergunta?