Webhooks do CustomerX

Neste artigo:

• Introdução

• Overview

• Como cadastrar um novo webhook

• Logs do webhook

• Eventos

Introdução

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.

Overview

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.

Como cadastrar um novo 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:

1. Descrição: informação que identifica o webhook.

2. Tipo de evento: escolha se deseja que o webhook seja disparado quando um registro for adicionado, atualizado, deletado ou qualquer evento.

3. Evento: escolha o objeto que deseja enviar entre cliente, contato, ticket, financeiro, tarefas da jornada do cliente e tarefas do CSM.

4. URL: informe a URL para qual será enviado o evento.

5. Usuário e Senha: caso possua autenticação, informe as credenciais do destino para que o webhook consiga se comunicar com sucesso.

6. Clique em "Salvar Webhook" e seu webhook será criado.
   

   

Logs de webhook

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:

1. Evento (Id): cada disparo do webhook gera um registro, aqui é exibido o identificador único do disparo.

2. 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.

3. 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:

1. Resposta: exibe a resposta recebida da URL destino.

2. 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.

Eventos

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.

Cliente

1. external_id_client: código do cliente

2. company_name: razão social

3. trading_name: fantasia

4. cnpj_cpf: CNPJ ou CPF

5. ie_rg: inscrição estadual ou CPF

6. date_register: data de registro

7. email: e-mail

8. cep: cep

9. state: estado

10. city: cidade

11. street: rua

12. branch_type: tipo de filial

13. district: rua

14. number: número

15. complement: complemento

16. facebook: link do facebook

17. linkedin: link do linkedin

18. twitter: link do twitter

19. instagram: link do instagram

20. youtube: link do youtube

21. site: link do site

22. parent_client_id: id da empresa matriz

23. parent_company: define se a empresa é matriz ou não (true or false)

24. only_journey_by_contract: parametro que define vinculo de jornada apenas por contrato

25. country: país

26. client_service_id: código da categoria de serviço

27. client_segment_id: código da categoria de segmento

28. client_group_id: código da categoria de grupo

29. quote_currency_id: código da moeda utilizada

30. phone: telefone

31. cancellation_date: data de cancelamento

32. created_at: data de criação

33. updated_at: data de atualização

34. is_excluded: define se o cliente foi excluído (true ou false)

35. exclusion_date: data de exclusão

36. contract_status: status do contrato

37. integration: dado da integração caso tenha sido importado de algum software terceiro

38. deleted_at: data de exclusão

39. 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":"exemplo@exemplo.com.br",
"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}

Contato

1. id: código do contato

2. name: nome do contato

3. email: e-mail do contato

4. occupation: cargo

5. birthday: data de nascimento

6. is_principal: define se é o contato principal (true ou false)

7. type_contact_id: código do tipo de contato

8. client_id: código interno do cliente

9. external_id_contact: código do cliente

10. note: observação

11. platform_active_user: define se o contato é usuário da plataforma

12. phone_fix: telefone 

13. phone_cel: celular

14. role: cargo

15. created_at: data de criação

16. updated_at: data de atualização

17. integration: dados da integração de origem

18. deleted_at: data de exclusão (caso tenha sido excluido)

19. origin: código da integração de origem

Exemplo:

{
id: 4716
name: "Nome Exemplo"
email: "nome@exemplo.com.br"
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}

Ticket

1. id: identificador interno do ticket no CustomerX

2. external_id: Identificador do ticket

3. title: Título do ticket aberto

4. description: Descrição do ticket

5. comment: Comentários do ticket

6. type_ticket: Tipo do ticket, ex: (BUG, ERRO, AJUDA, ...)

7. priority: Prioridade desse ticket

8. attendant_name: Nome do analista/atendente que prestará ajuda ao cliente

9. attendant_email: E-mail do analista/atendente que prestará ajuda ao cliente

10. date_opening: Data que foi aberto o ticket

11. date_reopening: Data de reabertura, caso o ticket foi reaberto

12. date_closing: Data em que o ticket foi fechado, caso o ticket já foi fechado

13. date_finalized: Data em que o ticket foi finalizado

14. date_deadline_attendance: Data do prazo para o ticket ser atendido

15. date_deadline_closing: Data do prazo para o ticket ser fechado

16. status: Status com base nos que foram descrito acima

17. created_at: data de criação

18. updated_at: data de atualização

19. client_id: código interno do cliente no CustomerX

20. contact_id: código interno do contato no CustomerX

21. group_name: nome do grupo

22. group_id: código do grupo

23. integration_url: URL do ticket na plataforma de origem

24. integration_url_label: "Alias" da URL do ticket, texto que será exibido na plataforma CustomerX e direcionará ao Ticket.

25. integration: dados adicionais da integração de origem

26. deleted_at: data de exclusão

27. 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}

Financeiro

1. external_id_financial: ID externo da movimentação

2. identifier: Identificador único da movimentação

3. description: Descrição para a movimentação

4. date_issue: Data de emissão

5. date_due: Data de vencimento da movimentação

6. value: Valor da movimentação

7. date_payment: Data de pagamento

8. discount_value: Valor de desconto (quando aplicado)

9. amount_paid: Valor pago

10. 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"}

Tarefa da jornada

1. id: código interno da tarefa;

2. description: descrição da tarefa;

3. title: título da tarefa;

4. date_closure: data de conclusão;

5. date_scheduled: data inicio agendada;

6. status: status da tarefa;

7. position: posição na lista;

8. created_at: data de criação;

9. updated_at: data de atualização;

10. customers_follow_up_id: código da lista da jornada;

11. user_id: código do usuário;

12. date_scheduled_final: data fim agendada;

13. contact_id: código do contato;

14. fixed_value: define se há pontuação fixa para esta tarefa;

15. value: pontos da tarefa;

16. default_tasks_follow_up_id: código da tarefa modelo;

17. late_task_sidekiq_job_id: código de controle interno;

18. creator_id: código do usuário que criou a tarefa;

19. reporter_id: código do usuário relator;

20. deleted_at: data de exclusão;

21. client: dados do cliente vinculado a tarefa

    1. extenal_id_client: código do cliente

    2. company_name: razão social do cliente

    3. trading_name: nome fantasia do cliente

    4. email: e-mail

    5. cnpj_cpf: CNPJ ou CPF

22. user: dados do usuário atrelado a tarefa

    1. id: código

    2. name: nome

    3. email: e-mail

23. reporter: dados do relator atrelado a tarefa

    1. id: código

    2. name: nome

    3. email: e-mail

24. creator: dados do criador da tarefa

    1. id: código

    2. name: nome

    3. email: e-mail

25. step: nome da lista da jornada

    1. description: descrição da etapa

    2. position: posição da lista na jornada

26. journey: dados da jornada

    1. id: código da jornada

    2. description: descrição da jornada

27. default_journey_id: código da jornada padrão

28. 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: "exemplo@email.com.br"
cnpj_cpf: "12.345.678/0001-00"
user:
id: 569
name: "João Exemplo"
email: "joao@exemplo.com"
reporter:
id: 569
name: "João Exemplo"
email: "joao@exemplo.com"
creator:
id: 569
name: "João Exemplo"
email: "joao@exemplo.com"
step:
description: "Engage"
position: 4
journey:
id: 999
description: "Ongoing"
default_journey_id: 9
products:null}

Tarefa do board de tarefas

1. title: Título da Tarefa

2. description: Descrição da Tarefa

3. date_scheduled: Data de início da Tarefa

4. client_id: ID interno do cliente

5. dashboard_activities_step_id: ID do tipo de contato 

6. date_scheduled_final: Data de início da Tarefa

7. date: Data da Tarefa (data de conclusão)

8. contact_id: código do contato

9. reporter_id: código do relator

10. filing_date: data de arquivamento

11. user_id: código do usuário

12. id: código interno da tarefa

13. status: Status da Tarefa (true/false)

14. created_at: data de criação

15. updated_at: data de atualização

16. position: Posição da Tarefa na lista do board, ordenado por ordem crescente

17. is_filed: booleano, define es a tarefa está arquivada

18. creator_id: código do criador da tarefa

19. deleted_at: data de exclusão

20. 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: "joao@exemplo.com"}