Como migrar webhooks?


Documentação oficial da nova API de webhooks

Os novos webhooks podem ser criados diretamente pela API, ao contrário da versão antiga que era necessário fazer esse passo diretamente pela interface do RD Station Marketing. No link acima mostramos como fazer a gestão dos mesmos (criar, atualizar, deletar e consultar).


Alterações - Payload Padrão

API 1.x Nova API
{
  "leads": [
    {
      "id": "1",
      "uuid": "c2f3d2b3-......-eef38be32f7f",
      "email": "email@email.com",
      "name": "Lead Name",
      "company": "Company Name",
      "job_title": "Job",
      "bio": "This is my bio",
      "created_at": "2012-06-04T15:31:35-03:00",
      "opportunity": "false",
      "number_conversions": "3",
      "user": "email@example.com",
      "first_conversion": {
        "content": {
          "identificador": "ebook-abc",
          "nome": "Lead Name",
          "email_lead": "email@email.com",
          "telefone": "99999999",
          "empresa": "Company Name",
          "cargo": "IT"
        },
        "created_at": "2012-06-04T15:31:35-03:00",
        "cumulative_sum": "1",
        "source": "source 1",
        "conversion_origin": {
          "source": "source 1",
          "medium": "medium 1",
          "value": "value 1",
          "campaign": "campaign 1",
          "channel": "channel 1"
        }
      },
      "last_conversion": {
        "content": {
          "identificador": "webinar-abc",
          "email_lead": "support@example.org"
        },
        "created_at": "2012-06-04T15:31:35-03:00",
        "cumulative_sum": "2",
        "source": "source 2"
      },
      "custom_fields": {},
      "website": "http://www.mywebsite.com",
      "personal_phone": "48 999999999",
      "mobile_phone": "48 999999999",
      "city": "Florianópolis",
      "state": "SC",
      "lead_stage": "Lead",
      "tags": [
        "tag 1",
        "tag 2"
      ],
      "fit_score": "d",
      "interest": 0
    }
  ]
}
        
{
  "event_type": "WEBHOOK.MARKED_OPPORTUNITY",
  "entity_type": "CONTACT",
  "event_identifier": "my-event-identifier",
  "timestamp": "2018-03-13T14:09:02.724-03:00",
  "event_timestamp": "2018-03-13T14:07:04.254-03:00",
  "contact": {
    "uuid": "c2f3d2b3-7250-4d27-97f4-eef38be32f7f",
    "email": "support@example.org",
    "name": "Contact Name",
    "job_title": "Developer",
    "bio": "This is my bio",
    "website": "http://rdstation.com.br",
    "personal_phone": "48 30252598",
    "mobile_phone": "48 30252598",
    "city": "Florianópolis",
    "facebook": "Contact Facebook",
    "linkedin": "Contact Linkedin",
    "twitter": "Contact Twitter",
    "tags": [
      "tag 1",
      "tag 2"
    ],
    "cf_custom_field_example": [
      "Option1",
      "Option2"
    ],
    "company": {
      "name": "Company Example 0"
    },
    "funnel": {
      "name": "default",
      "lifecycle_stage": "Lead",
      "opportunity": false,
      "contact_owner_email": "owner@example.org",
      "interest": 20,
      "fit": 0,
      "origin": "Orgânico"
    }
  }
}
        

Alterações - Campos/Atributos enviados no Payload


API 1.x Nova API
id Descontinuada (usar uuid)
uuid uuid
email email
name name
job_title job_title
bio bio
company company: { name }
number_conversions Descontinuada
user funnel: { contact_owner_email }
first_conversion Descontinuada
last_conversion event_identifier (quando gatilho for conversão)
custom_fields campos "cf_"
website website
personal_phone personal_phone
mobile_phone mobile_phone
city city
state state
lead_stage funnel: { lifecycle_stage }
tags tags
fit_score funnel: { fit }
interest funnel: { interest }
first_conversion.source / last_conversion.source funnel: { origin }

Observações importantes


first_conversion e last_conversion: Na versão antiga essa propriedade era enviada de forma fixa no pacote de dados do lead, na nova versão do webhook é enviado o estado atual do lead, então sempre que o gatilho de envio do webhook for conversão, o identificador que gerou o envio estará no atributo event_identifier, (que é o identificador que gerou o envio), já os dados são o do perfil do lead, que vai estar atualizado de acordo com a conversão, mas caso você precise desses dados, existe um endpoint de consulta de dados de conversão, basta fazer uma consulta após receber o lead.

public_url: Por questões de segurança e compliance esse atributo não estará mais disponível, ou seja, não será permitido deixar informações do lead de maneira pública.

O novo webhook permite que você defina se algumas informações farão parte do pacote de dados enviados a cada disparo, como por exemplo os dados de funil e empresa, para isso no momento de criação do webhook deve-se informar na propriedade include_relations COMPANY e CONTACT_FUNNEL, ambos opcionais.

Os campos personalizados não são enviados mais dentro de uma propriedade custom_fields como na versão anterior, agora eles ficam juntos dos dados do lead, identificados com o prefixo “cf_”, seguindo o padrão de identificadores dos campos personalizados, conforme explicado aqui.