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.
| Parameter | Description |
|---|---|
| Event action | The action done on an event object. |
| Event entity | The 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
| Parameter | Description |
|---|---|
| Endpoint URL | An 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
{
"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
| Parameter | Examples 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.
{
"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)"
}
...
]
}| Field | Explanation |
|---|---|
| "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)
{
"fk_id": "(string)",
"name": "(string)",
"description": "(string)",
"quantity": (int),
"unit_price": (int),
"unit": "(string)",
"type": "(string)"
}Order data
{
"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
{
"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
{
"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
{
"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_status | Meaning |
|---|---|
on_track | Less than 50% of the stage limit |
at_risk | Between 50% and 100% of the stage limit |
stalled | Reached or passed the stage limit |
null | The 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-
2xxresponse code or exceeding timeout of 10 seconds), we will try 5 more times:1st attempt: instantaneous (after fails)2nd attempt: after 6 seconds3rd attempt: after 18 seconds4th attempt: after 54 seconds5th 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.
