Como migrar webhooks?

šŸš§

ļø Caso ainda esteja utilizando a API 1.x de webhooks essa documentaĆ§Ć£o pode ser Ćŗtil para vocĆŖ.

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

{
  "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
    }
  ]
}

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

AlteraƧƵes - Campos/Atributos enviados no Payload

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

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.