O Ploomes conta com a funcionalidade de Webhooks. Para contextualizar, Webhooks são 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://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:
https://suporte.ploomes.com/integracoes/como-obter-acesso-a-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.

Encontrou sua resposta?