Webhooks

This section contains the documentation on the Webhooks provided by Ventiapp. What are they, what are available, how to create and delete them

What is a Webhook ?

Webhooks are a tool to retrieve and store data from a specific event. They allow you to register an https: // URL that Ventiapp would be calling when the registered event is fired. These are the events that we have webhook:

Evento	Topics
Orders	orders/created, orders/updated, orders/cancelled
Bills	bills/created
Products	products/created, products/updated. products/deleted

(*) Más eventos próximamente

API methods

List Webhooks

GET https://ventiapi.azurewebsites.net/api/webhooks/list

List of webhooks, we will return a list with the active webhooks in Ventiapp

Headers

Name	Type	Description
Authorization	string	Bearer + token
Content-Type	string	application/json

200

{
  "webhooks": [
    {
      "id": 1047897671,
      "address": "https://whatever.hostname.com/",
      "topic": "orders/created",
      "created_at": "2020-03-04T12:36:24-05:00",
      "api_version": "1.0.9"
    },
    {
      "id": 1047897673,
      "address": "https://whatever.hostname.com/",
      "topic": "orders/updated",
      "created_at": "2020-03-04T12:38:24-05:00",
      "api_version": "1.0.9"
    },
    {
      "id": 1047897678,
      "address": "https://whatever.hostname.com/",
      "topic": "bills/created",
      "created_at": "2020-03-04T12:39:24-05:00",
      "api_version": "1.0.9"
    },
  ]
}

Create Webhook

POST https://ventiapi.azurewebsites.net/api/webhooks/create

Creation of Webhook, here we must send the following data for a webhook to be created in Ventiapp. It is mandatory that the url be in https:// This will respond with the webhook ID, important to be able to delete it.

Headers

Name	Type	Description
Authorization	string	Bearer + token
Content-Type	string	application/json

200

{
  "webhook": {
    "id": 1047897671,
    "address": "https://whatever.hostname.com/",
    "topic": "orders/create",
    "created_at": "2020-03-04T12:38:24-05:00",
    "api_version": "1.0.9",
    "message": "Webhook created"
  }
}

Body Parameters

{
  "webhook": {
    "topic": "orders/created",
    "address": "https://whatever.hostname.com/",
  }
}

Delete Webhook

POST https://ventiapi.azurewebsites.net/api/webhooks/delete

Removal of Webhook, here we must the ID of the webhook to remove Bearer + token

Headers

Name	Type	Description
Content-Type	string	application/json

200

{
  "webhook": {
    "id": 1047897671,
    "address": "https://whatever.hostname.com/",
    "topic": "orders/create",
    "created_at": "2020-03-04T12:38:24-05:00",
    "api_version": "1.0.9",
    "message": "Webhook deleted"
  }
}

Body Parameters

{
  "webhook": {
    "id": 1047897671
  }
}

What does the webhook send ?

The webhook will notify the URL that an object was assigned according to the chosen event.

Orders:

{
      "orderId": 1234,
      "channel": "meli",
      "dateAdded": "2018-10-29T00:00:00",
      "dateCreated":"2018-10-29T00:00:00",
      "dateModified": "2018-10-29T00:00:00",
      "externalId": "111444123",
      "total": 660.0,
      "currency": "MXN",
      "tax": 0.16,
      "comments": "Send it before tuesday",
      "itemsQuantity": 2,
      "title": "Order Title",
      "internalStatus": 1,
      "amazonFulfillment": "false",
      "cartId": "00000101110002",
      "externalNumber" : "12314512",
      "items": [
        {
          "itemExternalId": "MLM3312341",
          "title": "Item 1",
          "price": 460.0,
          "variationId": "13818313",
          "variationName": "Red",
          "itemQuantity": 1,
          "total": 460.0,
          "sku": "ITEM-RED001",
          "erpId": null
        },
        {
          "itemExternalId": "MLM3317841",
          "title": "Item 2",
          "price": 200.0,
          "variationId": null,
          "variationName": null,
          "itemQuantity": 1,
          "total": 200.0,
          "sku": "PLAINITEM001",
          "erpId": null
        }
      ],
      "buyer": {
        "name": "John",
        "lastname": "Doe",
        "email": "[e-mail]",
        "state": "Distrito Federal",
        "address": "Street Address 123",
        "city": "Mexico City",
        "zipcode": "06700",
        "nickname": "JOHNDOEVENTI",
        "phone": "5584848152",
        "externalId": "551331413"
      },
      "shipping": {
        "sellerInfo": "MYSELLERNAME",
        "sellerId": null,
        "shipmentType": "me2",
        "shippingStatus": "shipped",
        "shippingCourier": "drop_off",
        "shippingId": "27586098188",
        "shippingType": "me2",
        "ventiShipping": false,
        "ventiCourierId": null,
        "shippingTrackingId": "10003313132",
        "shippingCourierExternal": "Fedex Express",
        "shippingCost": 120.0
      },
      "paymentMethods": [
                {
                    "externalId": "5531048951",
                    "paymentMethod": "oxxo"
                }
            ]
    }

Bills

{
      "orderId": 1234,
      "billingDate": "2018-06-06T00:00:00",
      "externalReference": "14124141",
      "externalDate": "2018-06-06T00:00:00",
      "message": "Billing message",
      "invoice": "0001",
      "total": 660.0,
      "cdfi": "04",
      "bankDigits": "1234",
      "paymentMethod": "03",
      "customer": {
        "name": "John",
        "businessName": "Doe",
        "rfc": "X3XXXXNNX0131",
        "email": "[e-mail]",
        "phone": "1139992331",
        "billingAddress": "fake street 123 101",
        "billingStreet": "fake street",
        "billingInnerNumber": "101",
        "billingOuterNumber": "123",
        "billingNeighborhood": "Condesa",
        "billingCountry": "Mexico",
        "billingState": "CDMX",
        "billingMunicipality": "Cuahutemoc",
        "billingZipCode": "06700"
      }
    }

Products:

{
    "productId": 3182093,
    "sku": "AA123",
    "price": 99.99,
    "title": "Olla a presion Gris",
    "ean": null,
    "upc": "41123123",
    "longDescription": "Descripcion larga de prueba",
    "shortDescription": "Descripción corta de prueba",
    "baseStock": 66,
    "images": ["url imagen 1","url imagen 2"],
    "brand": "Greycon",
    "weight": 2400,
    "height": 30,
    "width": 20,
    "depth": 20
}

Importants notes

Information variation

The information that travels through webhooks is completely dynamic, that is, it is possible that several fields change information, including shopping carts. This depends on the information that each sales channel informs us.

It is HIGHLY RECOMMENDED that the order update webhooks be implemented since in these the information may have a lot of variation.

Examples of information changes:

• Shipping information changes

• Cart changes (items)

• Changes in shipping costs

• Order status changes

• Shipping status changes

Another very important example is when the order is generated in the first instance, it is likely that you will not have a shipping guide or shipping information until a few minutes later, in which an order update will be triggered.

Mercado Libre Cart

Mercado Libre separates orders from the same cart in several calls. That is why the cartId field comes so that a grouping can be adapted from the development side.