Você com certeza já deve ter ouvido falar sobre webhooks. Mas afinal, o que são e para que servem? Webhooks são mecanismos de comunicação entre sistemas na web que permitem que um aplicativo envie informações automaticamente para outro aplicativo sempre que um determinado evento ocorre. Quando um evento ocorre, o aplicativo emissor envia uma mensagem HTTP para o webhook, que contém informações relevantes sobre o evento. O aplicativo receptor pode então usar essas informações para atualizar seu próprio estado ou tomar alguma outra ação automatizada com base nessa atualização.
O CustomerX conta com webhooks a partir do plano Growth e neste artigo vamos detalhar as funções desse poderoso recurso.
Você pode encontrar o recurso de webhooks clicando na engrenagem presente no canto superior direito e em seguida na opção "Webhooks".
Na tela de listagem de webhooks são exibidos todos os webhooks, juntamente com informação do tipo de evento, data de criação e status atual. Além disso também há uma opção para pesquisar um webhook específico caso desejado.
Clicando no botão "Opções" você também pode ver detalhes, editar, inativar ou excluir o webhook.
Para cadastrar um novo webhook, basta seguir os seguintes passos:
Na tela de listagem de webhooks, clique em "Novo Webhook" e no cadastro de webhook, preencha os seguintes campos:
Descrição: informação que identifica o webhook.
Tipo de evento: escolha se deseja que o webhook seja disparado quando um registro for adicionado, atualizado, deletado ou qualquer evento.
Evento: escolha o objeto que deseja enviar entre cliente, contato, ticket, financeiro, tarefas da jornada do cliente e tarefas do CSM.
URL: informe a URL para qual será enviado o evento.
Usuário e Senha: caso possua autenticação, informe as credenciais do destino para que o webhook consiga se comunicar com sucesso.
Clique em "Salvar Webhook" e seu webhook será criado.
Após o cadastro de um novo webhook, a primeira dúvida mais comum é "como saber se meu webhook está funcionando?". Para isso temos a opção de log dos disparos do webhook. Você pode acessar essa tela através da listagem de webhooks, clicando no botão "Opções" do webhook desejado e selecionando a opção "Detalhes".
Na primeira parte da tela de detalhes do webhook temos as informações básicas do webhook cadastrado, sendo elas: descrição, status, tipo de evento, evento, URL, usuário, senha, data de criação e quem criou.
Logo abaixo, temos presente os logs de envio, onde é apresentado:
Evento (Id): cada disparo do webhook gera um registro, aqui é exibido o identificador único do disparo.
Resposta/Status: representa a resposta recebida do destino após tentativa de comunicação. O código da resposta segue o código de status de resposta http, mas para facilitar o entendimento, caso esteja verde, significa que foi recebido com sucesso e vermelho houve algum problema na recepção.
Data do envio: data e hora em que o webhook foi disparado.
Ao clicar sobre um evento, são exibidos maiores detalhes do evento como:
Resposta: exibe a resposta recebida da URL destino.
Envio: apresenta detalhes do envio como id do evento, tipo do evento, evento e os dados enviados.
Importante: caso algum webhook tenha muitas falhas consecutivas, o criador do webhook receberá um e-mail informando e se as falhas persistirem o webhook será inativado automaticamente.
Para cada evento é disparado um objeto com diversos dados informados. Abaixo estão documentados os dados enviados para cada evento bem como exemplos de corpo de cada disparo.
external_id_client: código do cliente
company_name: razão social
trading_name: fantasia
cnpj_cpf: CNPJ ou CPF
ie_rg: inscrição estadual ou CPF
date_register: data de registro
email: e-mail
cep: cep
state: estado
city: cidade
street: rua
branch_type: tipo de filial
district: rua
number: número
complement: complemento
facebook: link do facebook
linkedin: link do linkedin
twitter: link do twitter
instagram: link do instagram
youtube: link do youtube
site: link do site
parent_client_id: id da empresa matriz
parent_company: define se a empresa é matriz ou não (true or false)
only_journey_by_contract: parametro que define vinculo de jornada apenas por contrato
country: país
client_service_id: código da categoria de serviço
client_segment_id: código da categoria de segmento
client_group_id: código da categoria de grupo
quote_currency_id: código da moeda utilizada
phone: telefone
cancellation_date: data de cancelamento
created_at: data de criação
updated_at: data de atualização
is_excluded: define se o cliente foi excluído (true ou false)
exclusion_date: data de exclusão
contract_status: status do contrato
integration: dado da integração caso tenha sido importado de algum software terceiro
deleted_at: data de exclusão
origin: código da integração de origem
Exemplo:
{"
"id":999,
"external_id_client":"9999",
"company_name":"Exemplo Razão Social",
"trading_name":"Exemplo Fantasia",
"cnpj_cpf":"12.345.678/0001-00",
"ie_rg":"0000000000",
"date_register":"2022-02-07T00:00:00.000-03:00",
"email":"[email protected]",
"cep":"00000000",
"state":"PR",
"city":"Curitiba",
"street":"Rua Exemplo",
"branch_type":"independent",
"district":"Centro",
"number":"9999",
"complement":"exemplo",
"facebook":"www.link.com/exemplo",
"linkedin":"www.link.com/exemplo",
"twitter":"www.link.com/exemplo",
"instagram":"www.link.com/exemplo",
"youtube":"www.link.com/exemplo",
"site":"www.link.com/exemplo",
"parent_client_id":null,
"parent_company":true,
"only_journey_by_contract":false,
"country":"Brasil",
"client_service_id":1,
"client_segment_id":1,
"client_group_id":1,
"quote_currency_id":1,
"phone":"+5545123456789",
"cancellation_date":null,
"created_at":"2022-02-08T09:08:28.490-03:00",
"updated_at":"2022-08-10T16:25:15.679-03:00",
"is_excluded":false,
"exclusion_date":null,
"contract_status":"active_contract",
"integration":{"pipedrive_id":9999},
"deleted_at":null,
"origin":9}id: código do contato
name: nome do contato
email: e-mail do contato
occupation: cargo
birthday: data de nascimento
is_principal: define se é o contato principal (true ou false)
type_contact_id: código do tipo de contato
client_id: código interno do cliente
external_id_contact: código do cliente
note: observação
platform_active_user: define se o contato é usuário da plataforma
phone_fix: telefone
phone_cel: celular
role: cargo
created_at: data de criação
updated_at: data de atualização
integration: dados da integração de origem
deleted_at: data de exclusão (caso tenha sido excluido)
origin: código da integração de origem
Exemplo:
{
id: 4716
name: "Nome Exemplo"
email: "[email protected]"
occupation: "Cargo de exemplo"
birthday: "01/01/1990"
is_principal: true
type_contact_id: 99
client_id: 999
external_id_contact: "ABC123"
note: "Exemplo"
platform_active_user: true
phone_fix: "45999999999"
phone_cel: "45999999999"
role: "Exemplo"
created_at: "2022-08-26T14:21:06.975-03:00"
updated_at: "2023-03-14T14:45:00.490-03:00"
integration:"pipedrive_id: 0000"
deleted_at: null
origin: 9}id: identificador interno do ticket no CustomerX
external_id: Identificador do ticket
title: Título do ticket aberto
description: Descrição do ticket
comment: Comentários do ticket
type_ticket: Tipo do ticket, ex: (BUG, ERRO, AJUDA, ...)
priority: Prioridade desse ticket
attendant_name: Nome do analista/atendente que prestará ajuda ao cliente
attendant_email: E-mail do analista/atendente que prestará ajuda ao cliente
date_opening: Data que foi aberto o ticket
date_reopening: Data de reabertura, caso o ticket foi reaberto
date_closing: Data em que o ticket foi fechado, caso o ticket já foi fechado
date_finalized: Data em que o ticket foi finalizado
date_deadline_attendance: Data do prazo para o ticket ser atendido
date_deadline_closing: Data do prazo para o ticket ser fechado
status: Status com base nos que foram descrito acima
created_at: data de criação
updated_at: data de atualização
client_id: código interno do cliente no CustomerX
contact_id: código interno do contato no CustomerX
group_name: nome do grupo
group_id: código do grupo
integration_url: URL do ticket na plataforma de origem
integration_url_label: "Alias" da URL do ticket, texto que será exibido na plataforma CustomerX e direcionará ao Ticket.
integration: dados adicionais da integração de origem
deleted_at: data de exclusão
origin: 33
Exemplo:
{
id: 9999
external_id: "0001"
title: "Conversa com João"
description: "Conversa com João"
comment: "Ticket sem comentário"
type_ticket: "Ticket"
priority: null
attendant_name: null
attendant_email: null
date_opening: "2023-03-14T10:37:18.000-03:00"
date_reopening: null
date_closing: null
date_finalized: null
date_deadline_attendance: null
date_deadline_closing: null
status: "open"
created_at: "2023-03-14T10:37:21.168-03:00"
updated_at: "2023-03-14T10:37:21.168-03:00"
client_id: 999
contact_id: 500
group_name: null
group_id: null
integration_url: "https://helpdesk.com/tickets/AAA"
integration_url_label: "9999"
integration: "zendesk:ticket_id: 9999"
deleted_at: null
origin: 33}external_id_financial: ID externo da movimentação
identifier: Identificador único da movimentação
description: Descrição para a movimentação
date_issue: Data de emissão
date_due: Data de vencimento da movimentação
value: Valor da movimentação
date_payment: Data de pagamento
discount_value: Valor de desconto (quando aplicado)
amount_paid: Valor pago
status: Status com base nos que descrito acima (pending, received, canceled, excluded)
Exemplo:
{"external_id_financial": "99999999","external_id_client": "49","identifier": "99999999","description": "Atrasada","date_issue": "02/04/2022","date_due": "02/04/2022","date_payment": "nil","value": 1000.00,"discount_value": 0.0,"status": "pending"}id: código interno da tarefa;
description: descrição da tarefa;
title: título da tarefa;
date_closure: data de conclusão;
date_scheduled: data inicio agendada;
status: status da tarefa;
position: posição na lista;
created_at: data de criação;
updated_at: data de atualização;
customers_follow_up_id: código da lista da jornada;
user_id: código do usuário;
date_scheduled_final: data fim agendada;
contact_id: código do contato;
fixed_value: define se há pontuação fixa para esta tarefa;
value: pontos da tarefa;
default_tasks_follow_up_id: código da tarefa modelo;
late_task_sidekiq_job_id: código de controle interno;
creator_id: código do usuário que criou a tarefa;
reporter_id: código do usuário relator;
deleted_at: data de exclusão;
client: dados do cliente vinculado a tarefa
extenal_id_client: código do cliente
company_name: razão social do cliente
trading_name: nome fantasia do cliente
email: e-mail
cnpj_cpf: CNPJ ou CPF
user: dados do usuário atrelado a tarefa
id: código
name: nome
email: e-mail
reporter: dados do relator atrelado a tarefa
id: código
name: nome
email: e-mail
creator: dados do criador da tarefa
id: código
name: nome
email: e-mail
step: nome da lista da jornada
description: descrição da etapa
position: posição da lista na jornada
journey: dados da jornada
id: código da jornada
description: descrição da jornada
default_journey_id: código da jornada padrão
products: produtos atrelados a jornada
Exemplo:
{
id: 19604
description: null
title: "Título Exemplo"
date_closure: null
date_scheduled: null
status: true
position: 31
created_at: "2023-03-14T13:35:02.884-03:00"
updated_at: "2023-03-14T13:35:02.884-03:00"
customers_follow_up_id: 2602
user_id: 999
date_scheduled_final: null
contact_id: null
fixed_value: false
value: "0.0"
default_tasks_follow_up_id: null
late_task_sidekiq_job_id: null
creator_id: 569
reporter_id: 569
deleted_at: null
client:
extenal_id_client: "2903"
company_name: "Exemplo razão social"
trading_name: "Exemplo fantasia"
email: "[email protected]"
cnpj_cpf: "12.345.678/0001-00"
user:
id: 569
name: "João Exemplo"
email: "[email protected]"
reporter:
id: 569
name: "João Exemplo"
email: "[email protected]"
creator:
id: 569
name: "João Exemplo"
email: "[email protected]"
step:
description: "Engage"
position: 4
journey:
id: 999
description: "Ongoing"
default_journey_id: 9
products:null}title: Título da Tarefa
description: Descrição da Tarefa
date_scheduled: Data de início da Tarefa
client_id: ID interno do cliente
dashboard_activities_step_id: ID do tipo de contato
date_scheduled_final: Data de início da Tarefa
date: Data da Tarefa (data de conclusão)
contact_id: código do contato
reporter_id: código do relator
filing_date: data de arquivamento
user_id: código do usuário
id: código interno da tarefa
status: Status da Tarefa (true/false)
created_at: data de criação
updated_at: data de atualização
position: Posição da Tarefa na lista do board, ordenado por ordem crescente
is_filed: booleano, define es a tarefa está arquivada
creator_id: código do criador da tarefa
deleted_at: data de exclusão
user: dados do usuário
Exemplo:
{
title: "Exemplo"
description: "Exemplo"
date_scheduled: null
client_id: null
dashboard_activities_step_id: 135
date_scheduled_final: null
date: "2023-03-15T14:53:35.262-03:00"
contact_id: null
reporter_id: 1
filing_date: null
user_id: 1
id: 2126
status: true
created_at: "2023-02-16T15:24:08.098-03:00"
updated_at: "2023-03-15T14:53:35.913-03:00"
position: 1
is_filed: false
creator_id: 1
deleted_at: null
user:
id: 1
name: "João Exemplo"
email: "[email protected]"}