Webhooks

O Webhook é a funcionalidade da API que possibilita a automatização do envio de dados e atividades do RD Station CRM para sistemas externos. Assim, é possível que você utilize o seu próprio aplicativo personalizado para ler, salvar e realizar ações com esses dados. Esta é uma opção poderosa que permite manter todos os seus dados em sincronia e abre a possibilidade para todos os tipos de integração.

Sempre que o evento configurado como gatilho no Webhook é acionado, o RD Station CRM fará o disparo de uma Negociação para integrações externas, contendo o payload padrão em JSON ("pacote de dados") único e imutável para a URL de destino, que vai vai conter todas as informações disponíveis da Negociação, o que inclui todos os campos padrão e personalizados que foram preenchidos.

🚧

Nota: Para utilizar o evento de negociação é necessário ter uma conta no RD Station CRM e ser assinante do plano PRO.

Requisitos para funcionamento dos Webhooks

Os Webhooks criados devem obedecer aos seguintes requisitos:

  • Ser capaz de receber e consumir dados em formato JSON;
  • Possuir certificado de segurança;
  • Ter compatibilidade para fazer a leitura do pacote de dados que o RD Station CRM envia.

Eventos que acionam o envio dos Webhooks

Negociação: envia informações sobre uma negociação presente no RD Station CRM.
Exemplo: Se ocorreu uma criação de negociação, atualização de informações ou deleção da negociação.

Os eventos que acionam o Gatilho do Webhook de Evento crm_deal_updated são:

  • Criação de negociação;
  • Marcação de venda e perda;
  • Atualização de:
    Responsável pela Negociação;
    Campos personalizados da Negociação
    Qualificação;
    Valor;
    Funil de vendas;
    Etapa do funil de vendas

Query params

Parâmetros utilizados para listar, exibir e deletar Webhooks.

NomeTipoDescrição
tokenStringToken do usuário
uuidStringO UUID exclusivo associado a cada webhook

Body params

Parâmetros utilizados para criar e atualizar Webhook.

NomeTipoDescriçãoObrigatório para criarobrigatório para atualizarobservação
tokenStringToken do usuário
uuidStringO UUID exclusivo associado a cada webhook
event_typeStringO tipo de evento que aciona a solicitação de webhook.Eventos suportados: crm_deal_created, crm_deal_updated e crm_deal_deleted
entity_typeStringA entidade da assinatura do webhook. Por enquanto, 'CONTATO' é a única opção aceitaEntidade suportada: CONTACT
urlStringA URL de destino do webhook
http_methodStringO método http que o webhook acionará. Atualmente, apenas o método 'POST' é suportadoMétodos suportados: POST

Webhooks CRM payload

Quando o evento configurado no Webhook é acionado, o RD Station CRM envia uma requisição com o método configurado no http_method com o cabeçalho Content-Type: application/json.

Abaixo seguem os campos disponíveis no payload da requisição para cada event_type possível:

Evento crm_deal_created

{
      {
   "event_name": "crm_deal_created",
   "document":{
      "id":"650878567482d9c0c7002050a475",
      "name":"Teste Negociação",
      "amount_monthly":0.0,
      "amount_unique":0.0,
      "amount_total":0.0,
      "prediction_date":null,
      "created_at":"2023-09-18T15:04:34.515-03:00",
      "updated_at":"2023-09-18T15:04:34.515-03:00",
      "rating":1,
      "status":"ongoing",
      "closed_at":null,
      "user":{
         "id":"622e7fb2f678470c001576f4a4",
         "name":"Hian Almada",
         "email":"[email protected]",
         "avatar_url":null
      },
      "deal_stage":{
         "id":"622e4cee412e87000d2f52a6",
         "name":"Sem contato",
         "nickname":"SC",
         "created_at":"2022-03-13T16:58:38.951-03:00",
         "updated_at":"2022-03-13T16:58:38.951-03:00",
         "order":1
      },
      "deal_pipeline":{
         "id":"622e4cee111e87000d2f52a5",
         "name":"Funil Padrão"
      },
      "deal_source":{
         
      },
      "campaign":{
         
      },
      "deal_lost_reason":{
         
      },
      "deal_custom_fields":[
         {
            "value":null,
            "custom_field":{
               "id":"611e89b0f269d0000b3bb2c2",
               "label":"Whatsapp",
               "required":false,
               "unique":false,
               "opts":[
                  
               ],
               "type":"text"
            }
         },
         {
            "value":null,
            "custom_field":{
               "id":"112e89ca673c7300162f15b3",
               "label":"Instagram",
               "required":false,
               "unique":false,
               "opts":[
                  
               ],
               "type":"text"
            }
         },
         {
            "value":null,
            "custom_field":{
               "id":"622e89e9f329d0000f3bb17a",
               "label":"Qual a sua idade?",
               "required":false,
               "unique":false,
               "opts":[
                  
               ],
               "type":"text"
            }
         },
         {
            "value":null,
            "custom_field":{
               "id":"622e8a32f269d0011f3bb17d",
               "label":"De onde você conhece a Issues?",
               "required":false,
               "unique":false,
               "opts":[
                  "Selecione",
                  "Redes Sociais",
                  "Indicação",
                  "Pesquisa no Goole",
                  "Evento",
                  "Pista de skate"
               ],
               "type":"option"
            }
         },
         {
            "value":null,
            "custom_field":{
               "id":"6258480fd71568001128705a",
               "label":"Unidade",
               "required":false,
               "unique":false,
               "opts":[
                  "Florianópolis",
                  "São Paulo"
               ],
               "type":"multiple_choice"
            }
         }
      ],
      "deal_products":[
         
      ]
   },
   "event_timestamp":"2023-09-18T18:04:34.000Z",
   "transaction_uuid":"f111b90-ec81-4353-8d52-ffd3b8df412d"
}

Evento crm_deal_updated

{
      {
   "event_name": "crm_deal_updated",
   "document":{
      "id":"650878567482d9c0c7002050a475",
      "name":"Teste Negociação",
      "amount_monthly":0.0,
      "amount_unique":0.0,
      "amount_total":0.0,
      "prediction_date":null,
      "created_at":"2023-09-18T15:04:34.515-03:00",
      "updated_at":"2023-09-18T15:04:34.515-03:00",
      "rating":1,
      "status":"ongoing",
      "closed_at":null,
      "user":{
         "id":"622e7fb2f678470c001576f4a4",
         "name":"Hian Almada",
         "email":"[email protected]",
         "avatar_url":null
      },
      "deal_stage":{
         "id":"622e4cee412e87000d2f52a6",
         "name":"Sem contato",
         "nickname":"SC",
         "created_at":"2022-03-13T16:58:38.951-03:00",
         "updated_at":"2022-03-13T16:58:38.951-03:00",
         "order":1
      },
      "deal_pipeline":{
         "id":"622e4cee111e87000d2f52a5",
         "name":"Funil Padrão"
      },
      "deal_source":{
         
      },
      "campaign":{
         
      },
      "deal_lost_reason":{
         
      },
      "deal_custom_fields":[
         {
            "value":null,
            "custom_field":{
               "id":"611e89b0f269d0000b3bb2c2",
               "label":"Whatsapp",
               "required":false,
               "unique":false,
               "opts":[
                  
               ],
               "type":"text"
            }
         },
         {
            "value":null,
            "custom_field":{
               "id":"112e89ca673c7300162f15b3",
               "label":"Instagram",
               "required":false,
               "unique":false,
               "opts":[
                  
               ],
               "type":"text"
            }
         },
         {
            "value":null,
            "custom_field":{
               "id":"622e89e9f329d0000f3bb17a",
               "label":"Qual a sua idade?",
               "required":false,
               "unique":false,
               "opts":[
                  
               ],
               "type":"text"
            }
         },
         {
            "value":null,
            "custom_field":{
               "id":"622e8a32f269d0011f3bb17d",
               "label":"De onde você conhece a Issues?",
               "required":false,
               "unique":false,
               "opts":[
                  "Selecione",
                  "Redes Sociais",
                  "Indicação",
                  "Pesquisa no Goole",
                  "Evento",
                  "Pista de skate"
               ],
               "type":"option"
            }
         },
         {
            "value":null,
            "custom_field":{
               "id":"6258480fd71568001128705a",
               "label":"Unidade",
               "required":false,
               "unique":false,
               "opts":[
                  "Florianópolis",
                  "São Paulo"
               ],
               "type":"multiple_choice"
            }
         }
      ],
      "deal_products":[
         
      ]
   },
   "event_timestamp":"2023-09-18T18:04:34.000Z",
   "transaction_uuid":"f111b90-ec81-4353-8d52-ffd3b8df412d"
}

Evento crm_deal_deleted

{
   "event_name":"crm_deal_deleted",
   "document":{
      "id":"64df7a11113f80018644923",
      "name":"Teste Negociação"
   },
   "event_timestamp":"2023-11-14T18:43:09.000Z",
   "transaction_uuid":"b2daa3cb-23b1-497f-afb5-a5e4acda9374"
}

Legenda dos campos enviados no payload padrão

Confira abaixo cada campo enviado pelo webhook e o que cada um deles representa:

NomeTipoDescrição
event_nameStringO tipo de evento que acionou a solicitação do webhook. Atualmente, apenas CRM_DEAL_CREATED, CRM_DEAL_UPDATED e CRM_DEAL_DELETED são opções válidas
event_timestampDateTimeA hora em que ocorreu o evento que acionou o webhook
transaction_uuidUUIDIdentificador único do evento
documentObjectObjeto contendo objetos com as informações da negociação
userObjectUsuário relacionado a negociação
deal_stageObjectEstágio da negociação no fluxo
deal_pipelineObjectFunil do CRM em que a negociação se encontra
deal_sourceObjectFonte da negociação
campaignObjectInformação das campanhas referente à entrada das negociações
deal_lost_reasonObjectMotivo da perda da negociação
deal_custom_fieldsObjectCampos personalizados da negociação
deal_productsObjectProdutos e serviços presentes na negociação
amount_uniqueObjectValor único
amount_monthlyObjectValor recorrente
amount_annualObjectValor total (soma do valor único e valor recorrente)

❗️

O webhook envia um payload padrão em JSON único e imutável.

Não é possível personalizar os dados enviados pelo webhook.

Retries Logic

Caso nosso serviço de webhooks tenha problemas ao entregar suas notificações, nós tentaremos enviá-las novamente 5 vezes.

Os possíveis problemas na entrega das notificações são:

  • Se seu endpoint de callback demorar mais de 5 segundos para responder.
  • Se a resposta do seu endpoint de callback tiver um status code diferente de 2xx.

Após a falha no envio acontecer, as notificações entram em uma fila para serem re-processadas. Caso o re-envio de uma notificação falhe 5 vezes seguidas, a notificação será marcada como falha e não será re-processada.

Seguindo essa lógica, se as notificações estejam chegando duplicadamente no seu sistema, é um indício de que o tempo de resposta do endpoint é maior do que 5 segundos.

🚧

Atenção em caso de Webhook suspenso

Para que um webhook seja suspenso é necessário que o mesmo esteja sempre retornando ERROS de forma constante, o que significa que a integração não está funcionando como deveria.

Sendo assim, é feito uma análise sobre esse erros, e caso seja constatado que o mesmo não será resolvido sozinho, pode acontecer a suspensão temporária.

Mais informações, acesse o artigo que apresenta mais detalhes sobre a ação