Skip to content

Webhooks

Overview

The Gelato API can be configured to send webhook events to notify your application any time that an event happens on your order.
The Gelato API sends the Event object, via a HTTP POST request, to any endpoint URLs that you have provided us.
The Event object contains all the relevant information about what just happened, including the type of event and the data associated with that event. Please refer to the API Portal to configure your account with a webhook URL.

Webhook URL

Your Webhook URL endpoint must be RESTful. All calls must be implemented as a HTTP post and with TLS encrypted. The HTTP response code 2xx is expected on positive calls, all other response codes will be considered as an error.

Request data

All events will be posted as JSON objects to your Webhook URL endpoint. The documentation for each webhook request is described below.

Response data

No response content is expected, any content will be ignored.

Retries

Webhooks will try to send the request data 3 times, with 5 seconds delay between each try, if an HTTP status 2xx is not returned.

Event objects

Order status

It is triggered when order status is changed. This event provides information about the new status of the order and its items, as well as its tracking codes if they are available.

Order status object example:

{
    "id": "os_5e5680ce494f6",
    "object": "orderStatus",
    "orderReferenceId": "{{MyOrderId}}",
    "fulfillmentStatus": "shipped",
    "items": [
        {
            "itemReferenceId": "{{MyItemId}}",
            "fulfillmentStatus": "shipped",
            "fulfillments": [
                {
                    "trackingCode": "code123",
                    "trackingUrl": "http://example.com/tracking?code=code123",
                    "carrierName":"DHL Express Domestic BR",
                    "carrierUid":"dhl_express_domestic_br",
                    "productionCountry":"BR",
                    "productionStateProvinceCode":"SP"
                },
                {
                    "trackingCode": "code234",
                    "trackingUrl": "http://example.com/tracking?code=code234",
                    "carrierName":"DHL Express Domestic BR",
                    "carrierUid":"dhl_express_domestic_br",
                    "productionCountry":"BR",
                    "productionStateProvinceCode":"SP"
                }
            ]
        }
    ]
}

Object parameters

Parameter Type Description
id string Unique identifier for the event.
object string String representing the event’s type. For order status event the value is orderStatus.
orderReferenceId string Reference to your internal order id.
fulfillmentStatus string Current status for your order, can be: created, uploading, passed, failed, canceled, printed or shipped
items OrderItem[] Array of order items, including reference id, current status and fulfillment details for each item

OrderItem parameters

Parameter Type Description
itemReferenceId string Reference to your internal item id.
fulfillmentStatus string Current status for your order item, can be: created, passed, failed, canceled, printed or shipped
fulfillments OrderItemFulfillment[] Array of fulfillment details for each order items. Each fulfillment contains information about tracking codes and shipping providers

OrderItemFulfillment parameters

Parameter Type Description
trackingCode string The tracking code of the package with your item.
trackingUrl string The URL to shipping provider page with tracking information about your package with the item.
carrierName string Name of the shipping provider specified including shipment method
carrierUid string Unique identifier of shipping provider inside Gelato system
productionCountry string Code of the country where the ordered product was produced
productionStateProvinceCode string Code of the state, province or region where the ordered product was produced

Item status

It is triggered when the status of an item has changed. This is a useful event to track information about your item, including notification if the item has been printed or if an error has occured.

Item status object example:

{
  "id": "is_5b6403bd3cf1f",
  "object": "itemStatus",
  "itemReferenceId": "{{MyItemId}}",
  "orderReferenceId": "{{MyOrderId}}",
  "status": "passed",
  "comment": "",
  "created": "2018-08-03T07:26:52+00:00"
}

Object parameters

Parameter Type Description
id string Unique identifier for the event.
object string String representing the event’s type. For item status event the value is itemStatus.
itemReferenceId string Reference to your internal item id.
orderReferenceId string Reference to your internal order id.
status string Current status for your order item, can be: passed, failed, canceled, printed or shipped
comment string Short text defining the reason for the status change.
created string Time at which the object was created. The value is in ISO-8601 format.

Tracking code

It is triggered when item is shipped, this event provides information about the tracking code and the shipping provider.

Tracking code object example:

{
  "id": "tc_5b6403bd3cf2e",
  "object": "trackingCode",
  "itemReferenceId": "{{MyItemId}}",
  "trackingCode": "code123",
  "trackingUrl": "http://example.com/tracking?code=code123",
  "carrierName":"DHL Express Domestic BR",
  "carrierUid":"dhl_express_domestic_br",
  "productionCountry":"BR",
  "productionStateProvinceCode":"SP",
  "created": "2018-08-03T12:11:30+00:00"
}

Object parameters

Parameter Type Description
id string Unique identifier for the event.
object string String representing the event’s type. For tracking code event the value is trackingCode.
itemReferenceId string Reference to your internal item id.
trackingCode string The tracking code of the package with your item.
trackingUrl string The URL to shipping provider page with tracking information about your package with the item.
carrierName string Name of the shipping provider specified including shipment method
carrierUid string Unique identifier of shipping provider inside Gelato system
productionCountry string Code of the country where the ordered product was produced
productionStateProvinceCode string Code of the state, province or region where the ordered product was produced
created string Time at which the object was created. The value is in ISO-8601 format.