Skip to content

Guide for Webhooks ​

About webhooks ​

Webhooks allow you to get programmatic notifications from Leads2b about events performed on your data when they happen.

When one of those events is triggered (for example a new customer is added), Leads2b will send this notification as an HTTP POST request, with a JSON body, to the endpoint(s) you specify.

You can create a new webhook in the Leads2b web app via Configurations > Apps and connections > Webhooks.

WARNING

This feature is available for some plans. Check your current plan and make sure it is available for you!

Events in Leads2b ​

With an event, you can filter what kind of events you want to receive.

ParameterDescription
Event actionThe action done on an event object.
Event entityThe object the action is done on.

TIP

Events in Leads2b are triggered both from the Leads2b Web app and from the API calls.

Endpoint outside Leads2b ​

ParameterDescription
Endpoint URLAn endpoint URL is the HTTP endpoint where your preferred events are sent. We can send them only to a full, valid and publicly accessible URL.

Webhook format ​

json
{
  "meta": {
    "id": xxx,
    "company_id": xxxxx,
    "object": "contact",
    "action": "created",
    "user_id": xxx,
    "date": "YYYY-MM-DD HH:mm:ss"
  },
  "data": (the object data as of this update)
}

TIP

The current data schema for Leads2b Webhooks is v1. Therefore, when configuring your webhook, the registered configuration is something like v1.contact.created, v1.order.updated, etc.

Webhook's meta block ​

ParameterExamples and explanations
"id"ID of the object
"company_id"ID of the company where the webhook was triggered in
"object"See supported objects types
"action"See supported event actions
"user_id"ID of user
"date"Created date from webhook

TIP

When the object has custom fields filled in, the data block also carries a custom_data object with those values.

Webhook's data block ​

The object data as of this update.

Contact and Customer data ​

The contact and customer objects represent the same entity and send exactly the same payload. The only difference is which event you subscribe to — see Contact and Customer.

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)"
    }
    ...
  ]
}
FieldExplanation
"type"PERSON for an individual or ORGANIZATION for a company. It is determined by whether the CNPJ is filled in.
"is_customer"true when the contact is already an actual customer (a won deal or a manual flag) and false while it is only a contact.

TIP

The first item of addresses is always the main address, identified by "type": "main", and has no id. The remaining ones are additional addresses, identified by "type": "additional".

Item data (products) ​

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

Order data ​

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

Quotation data ​

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

Lead data ​

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

Opportunity and After Sale data ​

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

Stage stagnation ​

Present on the lead, opportunity and after_sale objects. When the pipeline stage has a maximum time configured (stage_max_days), the payload reports how long the deal has been sitting in it and which state it is in:

stagnation_statusMeaning
on_trackLess than 50% of the stage limit
at_riskBetween 50% and 100% of the stage limit
stalledReached or passed the stage limit
nullThe stage has no limit configured, or the deal is already won, lost or removed

The value is a snapshot taken when the event fires. A deal that becomes stalled purely through the passage of time does not generate an event on its own.

Supported event actions ​

  • Created
  • Updated
  • Deleted
  • Won (available only for leads, opportunities and after sales)
  • Lost (available only for leads, opportunities and after sales)

Supported object types ​

  • Contact
  • Customer
  • Item
  • Order
  • Quotation
  • Lead
  • Opportunity
  • After Sale

TIP

View list of webhooks to see all available combinations of event objects and event actions for creating webhooks.

Contact and Customer ​

The contact object represents a contact — a person or an organization — and is the successor of the customer object. In Leads2b, a customer and a contact are the same entity: a customer is nothing more than a contact that has already closed a deal with you. That is why both objects are triggered by the same events and send the same payload, in which you can tell the cases apart through the type (PERSON or ORGANIZATION) and is_customer fields.

WARNING

The customer object will be deprecated in a future version, when only contact will remain available.

For now nothing changes: customer keeps working normally and you don't have to change anything right away. We do recommend, however, that new integrations already use contact, and that existing integrations plan the migration — which is only a matter of switching the event object, since the payload is the same.

Careful when subscribing to both

If you subscribe to contact and customer at the same time — including when you pick the All option while creating the webhook —, every change to a contact will generate two notifications, one for each object. Make sure your endpoint handles that duplication, or subscribe to only one of them.

Examples and explanations ​

You can configure notifications for events such as contact.created, order.updated, item.deleted. For example, if you want to receive a webhook notification when a contact is updated, choose contact as the event object and updated as the event action.

You can see all possible webhooks that can be created in Leads2b here

Retry logic ​

Webhooks retry policy is as follows:

  • In case the original notification sending attempt fails (due to receiving a non- 2xx response code or exceeding timeout of 10 seconds), we will try 5 more times:

  • 1st attempt: instantaneous (after fails)

  • 2nd attempt: after 6 seconds

  • 3rd attempt: after 18 seconds

  • 4th attempt: after 54 seconds

  • 5th attempt: after 162 seconds ≃ 2.7 minutes

INFO

The totally time for worst case (5 retries) is 4 minutes

If the delivery attempt fails in all these attempts, we will consider as an unsuccessful delivery.