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.
Query params
Parâmetros utilizados para listar, exibir e deletar Webhooks.
| Nome | Tipo | Descrição |
|---|---|---|
| token | String | Token do usuário |
| uuid | String | O UUID exclusivo associado a cada webhook |
Body params
Parâmetros utilizados para criar e atualizar Webhook.
| Nome | Tipo | Descrição | Obrigatório para criar | obrigatório para atualizar | observação |
|---|---|---|---|---|---|
| token | String | Token do usuário | ✓ | ✓ | |
| uuid | String | O UUID exclusivo associado a cada webhook | ✓ | ||
| event_type | String | O tipo de evento que aciona a solicitação de webhook. | ✓ | ✓ | Eventos suportados: crm_deal_created, crm_deal_updated e crm_deal_deleted |
| entity_type | String | A entidade da assinatura do webhook. Por enquanto, 'CONTATO' é a única opção aceita | ✓ | ✓ | Entidade suportada: CONTACT |
| url | String | A URL de destino do webhook | ✓ | ✓ | |
| http_method | String | O método http que o webhook acionará. Atualmente, apenas o método 'POST' é suportado | ✓ | ✓ | Métodos suportados: POST |
| include_relations | Array of strings | Quais itens adicionais serão fornecidos no payload do webhook | Opções válidas: 'COMPANY' e 'CONTACT_FUNNEL' |
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:
| Nome | Tipo | Descrição |
|---|---|---|
| event_name | String | O 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_timestamp | DateTime | A hora em que ocorreu o evento que acionou o webhook |
| transaction_uuid | UUID | Identificador único do evento |
| document | Object | Objeto contendo objetos com as informações da negociação |
| user | Object | Usuário relacionado a negociação |
| deal_stage | Object | Estágio da negociação no fluxo |
| deal_pipeline | Object | Funil do CRM em que a negociação se encontra |
| deal_source | Object | Fonte da negociação |
| campaign | Object | Informação das campanhas referente à entrada das negociações |
| deal_lost_reason | Object | Motivo da perda da negociação |
| deal_custom_fields | Object | Campos personalizados da negociação |
| deal_products | Object | Produtos e serviços presentes na negociação |
| amount_unique | Object | Valor único |
| amount_monthly | Object | Valor recorrente |
| amount_annual | Object | Valor 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