Como migrar webhooks?

ūüöß

ÔłŹ Caso ainda esteja utilizando a API 1.x de webhooks, essa documenta√ß√£o pode ser √ļtil para voc√™.

Atualmente existem duas vers√Ķes de API dispon√≠veis (1.x e 2.0):

  • Fluxos de Automa√ß√£o e Webhooks criados pela interface do RD Station Marketing: Consomem a API 1.x (API antiga).
  • Webhooks criados via API conforme descrito na p√°gina Criar um webhook: Consomem a API 2.0 (nova API).

Os novos webhooks (API 2.0) s√£o 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.

Caso você esteja em processo de migração da API, confira os detalhes abaixo com as mudanças referentes aos Webhooks.


Altera√ß√Ķes do payload padr√£o

A estrutura do payload das duas vers√Ķes da API dispon√≠veis atualmente (1.x e 2.0) s√£o diferentes. Portanto, √© importante adequar o seu sistema externo para consumir esses dados, conforme a vers√£o do Webhook criado na sua conta.

Confira abaixo o payload padr√£o enviado por cada uma das vers√Ķes:

API 1.x (API antiga)

{
  "leads": [
    {
      "id": "1",
      "uuid": "c2f3d2b3-......-eef38be32f7f",
      "email": "[email protected]",
      "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 protected]",
      "first_conversion": {
        "content": {
          "identificador": "ebook-abc",
          "nome": "Lead Name",
          "email_lead": "[email protected]",
          "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": "[email protected]"
        },
        "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
    }
  ]
}

API 2.0 (nova API)

{
  "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": "[email protected]",
    "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": "[email protected]",
      "interest": 20,
      "fit": 0,
      "origin": "Org√Ęnico"
    }
  }
}

Compara√ß√£o das altera√ß√Ķes dos campos/atributos enviados no payload

Caso esteja migrando os Webhooks da versão 1.x para 2.0, existe uma diferença nos campos e atributos enviados, bem como, em sua nomenclatura.

Confira a tabela abaixo para ver uma comparação entre todas as mudanças:

API 1.xNova API
idDescontinuada (usar uuid)
uuiduuid
emailemail
namename
job_titlejob_title
biobio
companycompany: { name }
number_conversionsDescontinuada
userfunnel: { contact_owner_email }
first_conversionDescontinuada
last_conversionevent_identifier (quando gatilho for convers√£o)
custom_fieldscampos "cf_"
websitewebsite
personal_phonepersonal_phone
mobile_phonemobile_phone
citycity
statestate
lead_stagefunnel: { lifecycle_stage }
tagstags
fit_scorefunnel: { fit }
interestfunnel: { interest }
first_conversion.source / last_conversion.sourcefunnel: { origin }

Observa√ß√Ķes importantes

Veja alguns detalhes importantes na mudança do payload padrão:

  • 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.
  • custom_fields: 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.
  • include_relations: 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.