# Webhooks

### 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

<mark style="color:blue;">`GET`</mark> `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 |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "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"
    },
  ]
}
```

{% endtab %}
{% endtabs %}

## Create Webhook

<mark style="color:green;">`POST`</mark> `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 |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "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"
  }
}
```

{% endtab %}
{% endtabs %}

Body Parameters

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

## Delete Webhook

<mark style="color:green;">`POST`</mark> `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 |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "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"
  }
}
```

{% endtab %}
{% endtabs %}

Body Parameters

```javascript
{
  "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:

```javascript
{
      "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": "email@api.com",
        "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

```javascript
{
      "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": "billing@test.com",
        "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:

```javascript
{
    "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&#x20;
* Cart changes (items)&#x20;
* Changes in shipping costs&#x20;
* Order status changes&#x20;
* 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.