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": "customer",
    "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.customer.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

Webhook's data block

The object data as of this update.

Customer data

{
  "fk_id": "(string)",
  "name": "(string)",
  "fantasy_name": "(string)",
  "email": "(string)",
  "ddd": "(string)",
  "cel_phone": "(string)",
  "credit_limit": (float),
  "comercial_phone": "(string)",
  "cnpj": "(string)",
  "cpf": "(string)",
  "observations": "(string)",
  "ie": "(string)",
  "restriction": "(string)",
  "addresses": [
    {
      "address": "(string)",
      "address_number": "(string)",
      "address_type": "(string)",
      "neighborhood": "(string)",
      "address_complement": "(string)",
      "city": "(string)",
      "uf": "(string)",
      "zipcode": "(string)"
    }
    ...
  ]
}

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_fk_id": "(string)",
  "customer_id_order": "(string)",
  "fk_id_freight": "(string)",
  "freight_value": "(string)",
  "fk_id_shipping": "(string)",
  "fk_id_payment_method": "(string)",
  "fk_id_payment_term": "(string)",
  "fk_id_payment_type": "(string)",
  "date": "(string)",
  "due_date": "(string)",
  "nf": "(string)",
  "num_itens": (int),
  "discount": (int),
  "approved": (int),
  "status": "(string)",
  "total_price": (int),
  "user_fk_id": "(string)",
  "observations": "(string)",
  "further_information": "(string)",
  "quotation_approval_message": "(string)",
  "estimated_delivery_date": "(string)",
  "estimated_billing_date": "(string)",
  "id_order_category": "(string)",
  "id_contract": "(string)",
  "items": [
    {
      "id": (int),
      "fk_id": "(string)",
      "name": "(string)",
      "description": "(string)",
      "quantity": (int),
      "item_fk_id": "(string)",
      "line_num": "(string)",
      "due_date": "(string)",
      "price": (float),
      "original_price": (float),
      "perc_desc": (float),
      "vlr_desc": (float)
    }
  ]
}

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

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

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

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

TIP

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

Examples and explanations

You can configure notifications for events such as customer.created, order.updated, item.deleted. For example, if you want to receive a webhook notification when a customer is updated, choose customer 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.