Visão Geral
Este documento visa mostrar como é feita a integração de uma conta de CRM externa com a plataforma de prospecção utilizando o Webhook.
O Webhook disponível no Catacliente envia para outros sistemas as informações dos contatos que demonstraram interesse no assunto definido em uma determinada campanha.
Quando um Webhook é disparado?
O webhook é disparado quando um usuário atribui pela primeira vez ou reclassifica o nível de
interesse para um contato. O webhook não é disparado caso o nível de interesse seja removido de um contato.
Passo-a-passo da integração
Na tela de configuração do Webhook, informe a URL de destino no campo especificado:
Figura 1 - Tela de configuração do webhook
O botão “Testar Webhook” envia uma requisição de teste para a URL informada e validará se o
webhook foi enviado com sucesso. Exemplos de retorno:
Figura 2 - Exemplo de webhook executado com sucesso
Figura 3 - Exemplo de erro ao executar
Retorno do teste da execução da URL
A URL deve retornar para o Catacliente o código HTTP 200 e no corpo da resposta retornar um
JSON, ou uma string qualquer que não seja uma página HTML, ou uma string vazia para ser considerada uma execução válida.
Exemplos válidos de retorno:
{"message":"Workflow was started"}
{"success":true,"message":"Success"}
Accepted
Formato do Webhook
{
"contact": {
"id": 0,
"name": "Contato Teste",
"invite_date": "2021-01-22 12:28:47",
"accept_date": "2021-01-22 12:28:47",
"collect_date": "2021-01-22 12:28:47",
"reply_date": null,
"linkedin_public_id": "contato-teste",
"current_company": "Empresa Teste",
"current_company_link": "http:\/\/linkpara.empresa.teste",
"role": "Teste",
"location": "S\u00e3o Paulo, Brasil",
"email": "teste@empresateste.com",
"phone": null,
"interest_level": 2,
"skills": [{
"skill": "skill 1",
"endorsements": 1
}, {
"skill": "skill 2",
"endorsements": 2
}],
"experiences": [{
"experience": "Experi\u00eancia 1",
"company_link": "http:\/\/linkpara.empresa.teste"
}]
},
"contact_owner": {
"id": 0,
"name": "Usu\u00e1rio Teste",
"email": "teste@teste.com"
},
"campaign": {
"id": 0,
"name": "Campanha Teste",
"description": "Descri\u00e7\u00e3o da campanha teste"
},
"messages": [{
"sender_name": "Usu\u00e1rio Teste",
"message": "mensagem de teste",
"date": "2021-01-22 12:28:47",
"pending_message": 0
}]
}
Detalhamento dos campos disponíveis
| Campo | Descrição |
|---|---|
| contact.id | Identificador numérico do contato. |
| contact.name | Nome do contato. |
| contact.invite_date | Data que o convite de conexão foi enviado. |
| contact.accept_date | Data que o convite de conexão foi aceito |
| contact.collect_date | Data que o contato foi inserido no sistema. |
| contact.reply_date | Data em que o usuário respondeu à nota de convite. |
| contact.linkedin_public_id | Identificador do perfil do usuário no LinkedIn. |
| contact.current_company | Nome da empresa atual do contato. |
| contact.current_company_link | URL da empresa atual do contato. |
| contact.role | Cargo do contato. |
| contact.location | Texto informando a localização do contato. |
| contact.email | E-mail do contato. |
| contact.phone | Telefone do contato (formato varia conforme o contato). |
| contact.interest_level | Nível de interesse do contato. 1 – Interesse baixo 2 – Interesse médio 3 – Interesse alto |
| contact.skills | Array com a lista de competências do contato. Dentro desse array, o campo “skill” informa o nome da competência, “endorsements” informa a quantidade de pessoas que confirmaram que o contato domina a competência em questão. |
| contact.experiences | Array com a lista de experiências prévias do contato. Dentro desse array, o campo “experience” descreve o cargo que o usuário ocupou anteriormente, “company_link” informa a URL da empresa. |
| contact_owner.id | Identificador numérico do usuário para o qual o contato está atribuído. |
| contact_owner.name | Nome do usuário. |
| contact_owner.email | E-mail do usuário. |
| campaign.id | Identificador numérico da campanha usada. |
| campaign.name | Nome da campanha. |
| campaign.description | Descrição da campanha. |
| messages | Array com a lista de mensagens trocadas com o contato. |
Detalhamento do array de mensagens (messages)
| Campo | Descrição |
|---|---|
| sender_name | Nome de quem enviou a mensagem. |
| message | Conteúdo da mensagem. |
| date | Data de envio da mensagem. |
| pending_message | Flag que indica se a mensagem está pendente de envio ou não (apenas para mensagens enviadas pelo Catacliente). 0 – Mensagem não está pendente 1 – Mensagem ainda não foi enviada |
Exemplo de recebimento de dados (PHP)
<?php
$json = file_get_contents('php://input');
// json convertido para array
$data = json_decode($json, true);
// processar o array $data ...
echo "Webhook recebido.";
?>
Integração com o Zapier
O Zapier fornece uma forma bem fácil de receber webhooks e processá-los. Para isso, basta seguir a documentação do próprio Zapier no link abaixo:
https://zapier.com/page/webhooks/
FAQ (Suporte)
1) Configurei o webhook, mas não aparece nada na ferramenta XYZ.
Verifique se foi informada uma URL válida durante a configuração dos webhooks. A URL informada deve ter sido criada especificamente para recebimento de webhook.
URLs de planilhas do Google e páginas iniciais de websites não processam dados enviados via POST. Ao usar a função de teste nessas URLs provavelmente será retornado HTTP 200, mas nada vai acontecer, pois nenhum processamento é feito pela URL de destino.
Também verifique se a URL é pública e não está bloqueada por logins e/ou firewalls para acesso
externo.
Observação: o Catacliente não é responsável pelo processamento dos dados pela URL informada
pelo cliente. O sistema apenas envia as informações, o que acontece depois disso não está no escopo de atuação do Catacliente.
2) O formato dos dados enviados pelo Catacliente não é compatível com o meu sistema. Preciso que o webhook envie dados em um formato diferente.
Não é possível mudar o formato do JSON enviado para o webhook. O padrão utilizado pelo
Catacliente foi criado de forma a conter todas as informações possíveis de um contato.
Caso seja necessário receber dados em outro formato, recomenda-se que a URL destino faça um
pré-processamento dos dados recebidos do Catacliente e os reenvie para o sistema que possui o formato personalizado. O sistema de integrações Zapier é uma ferramenta criada justamente com esse propósito.
3) Quero configurar o webhook para um usuário específico. É possível?
Webhooks são configurados apenas por empresa.