Skip to content

Guia para webhooks ​

Sobre os webhooks ​

Webhooks permitem a você programar notificações da Leads2b sobre eventos realizados em seus dados quando eles acontecem.

Quando um desses eventos é acionado (por exemplo um novo cliente é criado), a Leads2b vai enviar essa notificação como uma requisição HTTP POST, com um corpo/payload JSON para o endereço que você especificou.

Você pode criar um novo webhook no sistema Leads2b através do Menu Configurações > Apps e Conexões > Webhooks.

WARNING

Essa funcionalidade está disponível para alguns planos. Verifique seu plano atual e garanta que isso esteja disponível para você!

Eventos na Leads2b ​

Com um evento, você pode filtrar quais tipos de notificações você quer receber.

ParâmetroDescrição
Ação do eventoA ação realizada em uma entidade/objeto.
Objeto do eventoA entidade/objeto que a ação foi realizada.

TIP

Eventos na Leads2b são disparados tanto pela utilização do sistema web quanto por chamadas externas da API.

Endereço externo à Leads2b ​

ParâmetroDescrição
Endereço URLUm endereço HTTP onde seus eventos selecionados são enviados. Nós podemos enviá-los somente à uma URL completa, válida e publicamente acessível.

Formato do webhook ​

json
{
  "meta": {
    "id": xxx,
    "company_id": xxxxx,
    "object": "contact",
    "action": "created",
    "user_id": xxx,
    "date": "YYYY-MM-DD HH:mm:ss"
  },
  "data": (os dados do objeto a partir desta atualização)
}

TIP

O schema de dados atual dos Webhooks Leads2b é o v1. Portando, ao configurar seu webhook, a configuração registrado é algo como v1.contact.created, v1.order.updated, etc.

Bloco meta do webhook ​

ParâmetroExemplos e explicações
"id"ID do objeto
"company_id"ID da empresa da qual o webhook foi acionado
"object"Veja tipos de objetos suportados
"action"Veja ações de evento suportadas
"user_id"ID do usuário
"date"Data de criação do evento

TIP

Quando o objeto possui campos personalizados preenchidos, o bloco data também carrega um objeto custom_data com esses valores.

Bloco data do webhook ​

Os dados do objeto/entidade enviados na atualização.

Dados de Contato e de Cliente ​

Os objetos contact e customer representam a mesma entidade e enviam exatamente o mesmo payload. A diferença está apenas em qual evento você assina — veja Contato e Cliente.

json
{
  "name": "(string)",
  "fantasy_name": "(string)",
  "email": "(string)",
  "ddd": "(string)",
  "cel_phone": "(string)",
  "comercial_phone": "(string)",
  "cnpj": "(string)",
  "cpf": "(string)",
  "type": "(string)",
  "is_customer": (boolean),
  "fk_id": "(string)",
  "observations": "(string)",
  "ie": "(string)",
  "restriction": "(string)",
  "credit_limit": (float),
  "tags": ["(string)"],
  "responsibles": [
    {
      "id_user": (int),
      "user_fk_id": "(string)"
    }
    ...
  ],
  "contacts": [
    {
      "id": (int),
      "name": "(string)",
      "email": "(string)",
      "phone": "(string)",
      "department_name": "(string)",
      "fk_id": "(string)"
    }
    ...
  ],
  "addresses": [
    {
      "id": (int),
      "type": "(string)",
      "name": "(string)",
      "address": "(string)",
      "address_number": "(string)",
      "address_type": "(string)",
      "neighborhood": "(string)",
      "address_complement": "(string)",
      "city": "(string)",
      "uf": "(string)",
      "zipcode": "(string)",
      "fk_id": "(string)"
    }
    ...
  ]
}
CampoExplicação
"type"PERSON para pessoa física ou ORGANIZATION para pessoa jurídica. É determinado pelo preenchimento do CNPJ.
"is_customer"true quando o contato já é um cliente efetivo (negócio ganho ou marcação manual) e false enquanto ele for apenas um contato.

TIP

O primeiro item de addresses é sempre o endereço principal, identificado por "type": "main", e não possui id. Os demais são endereços adicionais, identificados por "type": "additional".

Dados de Item (produtos) ​

json
{
  "fk_id": "(string)",
  "name": "(string)",
  "description": "(string)",
  "quantity": (int),
  "unit_price": (int),
  "unit": "(string)",
  "type": "(string)"
}

Dados de Pedido ​

json
{
  "fk_id": "(string)",
  "customer_id": (int),
  "customer_name": "(string)",
  "contact_name": "(string)",
  "customer_fk_id": "(string)",
  "customer_id_order": "(string)",
  "fk_id_freight": "(string)",
  "freight_value": "(string)",
  "fk_id_shipping": "(string)",
  "fk_id_payment_term": "(string)",
  "fk_id_payment_type": "(string)",
  "quotation_id": (int),
  "fk_id_quotation": "(string)",
  "date": "(string)",
  "due_date": "(string)",
  "nf": "(string)",
  "num_itens": (int),
  "discount": (float),
  "approved": (int),
  "status": "(string)",
  "total_price": (float),
  "user_id": (int),
  "user_fk_id": "(string)",
  "user_email": "(string)",
  "observations": "(string)",
  "further_information": "(string)",
  "quotation_approval_message": "(string)",
  "estimated_delivery_date": "(string)",
  "estimated_billing_date": "(string)",
  "id_order_category": (int),
  "fk_id_order_category": "(string)",
  "id_contract": "(string)",
  "customer_type": (int),
  "customer_city": "(string)",
  "items": [
    {
      "id": (int),
      "fk_id": "(string)",
      "name": "(string)",
      "description": "(string)",
      "type": "(string)",
      "quantity": (float),
      "item_fk_id": "(string)",
      "line_num": "(string)",
      "due_date": "(string)",
      "price": (float),
      "original_price": (float),
      "perc_desc": (float),
      "vlr_desc": (float),
      "icms": (float),
      "base_icms": (float),
      "value_icms": (float),
      "icms_st": (float),
      "base_icms_st": (float),
      "value_icms_st": (float),
      "ipi": (float),
      "base_ipi": (float),
      "value_ipi": (float)
    }
  ],
  "address": {
    "address": "(string)",
    "address_number": "(string)",
    "neighborhood": "(string)",
    "address_complement": "(string)",
    "city": "(string)",
    "uf": "(string)",
    "zipcode": "(string)",
    "fk_id": "(string)"
  }
}

Dados de Orçamento ​

json
{
  "fk_id": "(string)",
  "title": "(string)",
  "date": "(string)",
  "customer_id": (int),
  "customer_name": "(string)",
  "contact_name": "(string)",
  "customer_fk_id": "(string)",
  "fk_id_payment_term": "(string)",
  "fk_id_payment_type": "(string)",
  "id_opportunity": (int),
  "client_status": (int),
  "approved": (int),
  "user_id": (int),
  "user_email": "(string)",
  "user_fk_id": "(string)",
  "observations": "(string)",
  "scope": "(string)",
  "estimated_billing_date": "(string)",
  "customer_id_order": "(string)",
  "id_contract": "(string)",
  "customer_type": (int),
  "customer_city": "(string)",
  "deleted_at": "(string)",
  "items": [
    {
      "id": (int),
      "id_item": (int),
      "item_fk_id": "(string)",
      "name": "(string)",
      "description": "(string)",
      "type": "(string)",
      "quantity": (float),
      "price": (float),
      "original_price": (float),
      "cost": (float),
      "icms": (float),
      "base_icms": (float),
      "value_icms": (float),
      "icms_st": (float),
      "base_icms_st": (float),
      "value_icms_st": (float),
      "ipi": (float),
      "base_ipi": (float),
      "value_ipi": (float),
      "recurrency_period": (int),
      "financial_cost": (float),
      "shipping_cost": (float)
    }
  ],
  "address": {
      "address": "(string)",
      "address_number": "(string)",
      "neighborhood": "(string)",
      "address_complement": "(string)",
      "city": "(string)",
      "uf": "(string)",
      "zipcode": "(string)",
      "fk_id": "(string)"
  }
}

Dados de Lead ​

json
{
  "company_name": "(string)",
  "social_reason": "(string)",
  "email": "(string)",
  "addresses": [
    {
      "address": "(string)",
      "city": "(string)",
      "state": "(string)",
      "zipcode": "(string)"
    }
  ],
  "phone": "(string)",
  "main_email": "(string)",
  "main_phone": "(string)",
  "main_contact": "(string)",
  "vendor": "(string)",
  "group": "(string)",
  "id_pipeline": (int),
  "pipeline_name": "(string)",
  "id_pipeline_item": (int),
  "pipeline_item_name": "(string)",
  "origin_name": "(string)",
  "status": "(string)",
  "loss_reason": "(string)",
  "lost_at": "(string)",
  "won_at": "(string)",
  "created_at": "(string)",
  "updated_at": "(string)",
  "deleted_at": "(string)",
  "g_clid": "(string)",
  "fb_clid": "(string)",
  "stagnation_status": "(string|null)",
  "days_in_stage": (int),
  "stage_max_days": (int|null)
}

Dados de Oportunidade e Pós-venda ​

json
{
  "name": "(string)",
  "description": "(string)",
  "company_name": "(string)",
  "social_reason": "(string)",
  "id_customer": (int),
  "customer_name": "(string)",
  "customer_phone": "(string)",
  "customer_email": "(string)",
  "id_contact": (int),
  "contact_name": "(string)",
  "contact_phone": "(string)",
  "contact_email": "(string)",
  "id_responsible": (int),
  "responsible": "(string)",
  "id_pipeline": (int),
  "pipeline_name": "(string)",
  "id_pipeline_item": (int),
  "pipeline_item_name": "(string)",
  "id_origin": (int),
  "origin_name": "(string)",
  "items": [
    {
      "id": (int),
      "name": "(string)",
      "description": "(string)",
      "unit": "(string)",
      "fk_id": "(string)",
      "amount": (int),
      "unit_price": (float),
      "price": (float)
    }
  ],
  "loss_reason": "(string)",
  "lost_at": "(string)",
  "won_at": "(string)",
  "created_at": "(string)",
  "updated_at": "(string)",
  "deleted_at": "(string)",
  "g_clid": "(string)",
  "fb_clid": "(string)",
  "stagnation_status": "(string|null)",
  "days_in_stage": (int),
  "stage_max_days": (int|null)
}

Estagnação na etapa ​

Presente nos objetos lead, opportunity e after_sale. Quando a etapa do funil tem um tempo máximo configurado (stage_max_days), o payload informa há quanto tempo o negócio está nela e em que estado ele se encontra:

stagnation_statusSignificado
on_trackMenos de 50% do tempo máximo da etapa
at_riskEntre 50% e 100% do tempo máximo
stalledAtingiu ou passou do tempo máximo
nullA etapa não tem tempo máximo configurado, ou o negócio já foi ganho, perdido ou removido

O valor é um retrato do momento do evento. Um negócio que passa a ficar estagnado apenas pela passagem do tempo não gera um novo evento por si só.

Ações de evento suportadas ​

  • Created
  • Updated
  • Deleted
  • Won (disponível apenas para leads, oportunidades e pós-vendas)
  • Lost (disponível apenas para leads, oportunidades e pós-vendas)

Tipos de objetos suportados ​

  • Contact
  • Customer
  • Item
  • Order
  • Quotation
  • Lead
  • Opportunity
  • After_Sale

TIP

Acesse lista de webhooks para ver todas as combinações de objetos e ações para criação de webhooks.

Contato e Cliente ​

O objeto contact representa um contato — uma pessoa ou uma organização — e é o sucessor do objeto customer. Na Leads2b, cliente e contato são a mesma entidade: um cliente nada mais é do que um contato que já fechou negócio com você. Por isso os dois objetos são disparados pelos mesmos acontecimentos e enviam o mesmo payload, no qual você pode distinguir os casos pelos campos type (PERSON ou ORGANIZATION) e is_customer.

WARNING

O objeto customer será descontinuado em uma versão futura, quando apenas contact permanecerá disponível.

Por enquanto nada muda: customer segue operando normalmente e você não precisa fazer nenhuma alteração agora. Recomendamos, porém, que novas integrações já utilizem contact, e que as integrações existentes planejem a migração — que consiste apenas em trocar o objeto do evento, já que o payload é o mesmo.

Atenção ao assinar os dois

Se você assinar contact e customer ao mesmo tempo — inclusive ao escolher a opção Todos na criação do webhook —, cada alteração de um contato vai gerar duas notificações, uma de cada objeto. Garanta que seu endpoint trate essa duplicidade ou assine apenas um dos dois.

Exemplos e explicações ​

É possível configurar notificações para eventos como contact.created, order.updated, item.deleted. Por exemplo, se você deseja receber webhook para notificá-lo quando um contato for alterado, escolha contact como o objeto do evento e updated como a ação do evento.

Você pode ver todos os webhooks que podem ser criados na Leads2b aqui

Lógica de Retentativa ​

Política de retentativa de webhooks é a seguinte:

  • No caso da tentativa original de notificação falhar (recebendo um código de resposta diferente de 2xx ou excedendo o tempo limite de 10 segundos), nós iremos tentar mais 5 vezes:

  • 1ª tentativa: instantânea (logo após falhar)

  • 2ª tentativa: depois de 6 segundos

  • 3ª tentativa: depois de 18 segundos

  • 4ª tentativa: depois de 54 segundos

  • 5ª tentativa: depois de 162 segundos ≃ 2.7 minutos

INFO

O tempo total para o pior cenário (5 retentativas) é de 4 minutos.

Se a tentativa de entrega falhar em todas essas tentativas, iremos considerar como uma entrega mal sucedida.