O que é um webhook?

Webhooks (também chamados de push notifications, gatilhos ou notificações de eventos) são usados para que seu sistema receba avisos do Arivo CRM de que um evento específico aconteceu em sua conta de grupo. Webhooks são usados para simplificar a integração entre o Arivo CRM e outros sistemas.

Entre os eventos que podem ser monitorados estão a criação de contatos, conclusão de atividades e fechamento de oportunidades.

Os passos para se usar um webhook são os seguintes

1. Crie um webhook para monitorar um tipo de evento. Ao criar um webhook você deve fornecer uma URL de callback.
2. Quando o evento monitorado ocorre no sistema, o Arivo CRM dispara uma chamada POST para a URL de callback do webhook, contendo em seu corpo o objeto alvo do evento. Esse objeto é representado no formato JSON, no mesmo formato usado na API REST.
3. Ao receber essa requisição na URL de callback, seu sistema deve retornar o código HTTP 200 para indicar que recebeu com sucesso a notificação do webhook.
4. Quando não quiser mais receber as notificações desse evento, você pode remover o webhook do sistema.

Cada URL de callback só pode ter no máximo um webhook de cada tipo de evento, caso contrário a URL sempre receberia requisições repetidas.

Tipos de eventos

Estes são os tipos de eventos que podem ser monitorados pelos webhooks do Arivo CRM.

• Contato (pessoa ou empresa) foi criado.
• Contato (pessoa ou empresa) foi atualizado.
• Contato (pessoa ou empresa) foi apagado.
• Contato do tipo pessoa foi criado.
• Contato do tipo pessoa foi atualizado.
• Contato do tipo pessoa foi apagado.
• Empresa foi criada.
• Empresa foi atualizada.
• Empresa foi apagada.
• Atividade foi criada.
• Atividade foi atualizada.
• Atividade foi apagada.
• Atividade foi finalizada.
• Atividade finalizada foi alterada para não finalizada.
• Oportunidade foi criada.
• Oportunidade foi alterada.
• Oportunidade foi apagada.
• Oportunidade foi fechada com sucesso.
• Oportunidade foi fechada e perdida.
• Oportunidade que estava fechada foi reaberta.
• Anotação foi criada.
• Anotação foi atualizada.
• Anotação foi apagada.

Status de webhook

Webhooks podem estar em um dos seguintes status:

• Ativo: o webhook está pronto para disparar requisições para a URL de callback quando o tipo de evento ocorre no sistema.
• Aguardando: para não enviar uma quantidade muito alta de chamadas em um curto período de tempo, o webhook pode entrar neste status em que deverá aguardar alguns minutos antes de enviar uma nova requisição.
• Inativo: o webhook não está disparando requisições. Isso ocorre porque algum erro indicou que a URL de callback não está funcionando ou ocorreu um número grande de erros comuns em um curto período de tempo. É possível reativá-lo com uma chamada para atualizar o webhook.

Formato da notificação

Toda notificação gerada por um webhook é feita através de uma requisição POST por HTTP. Para garantir que os dados não sejam interceptados utilize SSL no servidor que vai receber a chamada de callback (URL iniciado por https e servidor web configurado com certificado reconhecido pelos navegadores atuais).

O corpo da requisição é sempre no formato JSON e contém um array de objetos nesse formato. O formato de cada objeto é o mesmo que é retornado pelas chamadas da API REST.

O cabeçalho X-Arivo-Event contém o tipo de evento que disparou a notificação.

O cabeçalho X-Arivo-Event-Time contém a timestamp (milissegundos desde a meia noite de 1 de janeiro de 1970 UTC) em que o evento ocorreu no Arivo CRM. Como notificações podem ser enviadas fora de ordem é importante levar em consideração este cabeçalho.

Resposta de callback

Em caso de sucesso, o status HTTP 200 (ou 201 ou 204) deve ser retornado. Não é necessário retornar nenhum conteúdo no corpo da resposta.

Caso a URL de callback retorne o código HTTP 410 ou 404, o webhook é removido do sistema e não são feitas novas tentativas de envio de notificação.

Em caso de outros códigos HTTP, o Arivo CRM aguarda algum tempo antes de tentar novamente enviar a notificação. O webhook tem seu status alterado para parado (STOPPED) depois de um grande número de tentativas sem sucesso. O usuário pode reativar o webhook com uma chamada para atualizar o webhook pela API depois de ter resolvido os problemas que causaram os erros.

Se o servidor da URL de callback levar mais de 10 segundos para responder, o Arivo CRM considera que a requisição atual gerou um erro por limite de tempo e tenta novamente mais tarde. Para que isso não aconteça recomendamos gravar o conteúdo da requisição e deixar qualquer processamento que possa tomar mais tempo para ser executado depois de responder à requisição.

Uma requisição que seu servidor considerou como sucesso pode ter sido marcada com erro por limite de tempo e pode ser reenviada. Por isso é importante que o servidor da URL de callback consiga lidar com o caso de requisições duplicadas.

Verificação de segurança

A URL de callback não pode estar protegida por métodos de autenticação como HTTP Basic ou OAuth. Para que você possa verificar que a requisição veio do Arivo CRM, você pode configurar o webhook para enviar um cabeçalho contendo um hash gerado a partir do corpo da requisição e que pode ser usado para verificar sua autenticidade.

Para usar esse método de verificação, você deve fornecer uma chave secreta no campo secret ao criar ou alterar um webhook. Depois disso, as próximas notificações vão conter um cabeçalho com nome X-Hub-Signature contendo o valor sha1=.

Esse hash é a representação hexadecimal do HMAC usando algoritmo criptográfico SHA-1 aplicado no conteúdo do corpo da requisição, usando a chave secreta fornecida ao webhook. Ou em código Ruby:

    require 'openssl'

    hash_gerado = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha1'), sua_chave_secreta, dados_do_corpo)

Um exemplo de código, usando Ruby on Rails 4, que poderia ser usado para verificar uma requisição:

    def verify(request, secret_key)
        body_content = request.body.read
        request_hash = request.headers["X-Hub-Signature"]
        signature = 'sha1=' + OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha1'), secret_key, body_content)
        signature_is_authentic = Rack::Utils.secure_compare(request_hash, signature)
        return signature_is_authentic
    end

No método acima, a função Rack::Utils.secure_compare é usada para comparar strings em tempo constante. Isso é aconselhado para evitar alguns tipos de ataque que exploram o tempo usado durante uma comparação de string normal que retorna um resultado logo que encontra um caracter que invalida a checagem de igualdade.

Este é um artigo de ajuda do Arivo CRM.