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
Authorization
string
Bearer + token
Content-Type
string
application/json
{
"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
Authorization
string
Bearer + token
Content-Type
string
application/json
{
"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
Content-Type
string
application/json
{
"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": "[email protected]",
"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": "[email protected]",
"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.
Última actualización