Dropship Webhooks

This guide describes how iQmetrix Partners can use Dropship Webhooks to be notified of new and updated dropship orders.

What is a Webhook?

A webhook is an HTTP call-back from a source system to a client system designed to eliminate the need to poll the application to see if anything changed.

The client subscribes to a webhook for each event they are interested in and provides a URL for the event notifications to be sent to.

When an event occurs, the source system pushes a notification to the client system.

Creating a Dropship Webhook

To create a Dropship Webhook, make a request to the Create a Dropship Webhook endpoint specifying the event you are interested in and the URL of an endpoint that will “listen” for webhook notifications and process them appropriately.

It is your responsibility to implement this “listener”.

Once registered, the iQmetrix Dropship Service will send a HTTP POST request to the specified URL every time a relevant event occurs.

Receiving a Webhook

A webhook notification is sent as an HTTP POST request to the listening endpoint.

The notification will contain JSON that includes:

It is up to the receiving endpoint to verify the notification and send the appropriate response.

Responding to a Webhook

To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code. This tells the source system that the notification was successfully received.

iQmetrix APIs interpret any response codes outside the 2xx range to mean that you did not receive the webhook.

Any additional information returned in request headers or in the request body is ignored.

Retries on Failure

If the expected 2xx response is not received, the API will retry at 60-second intervals to a maximum of 5 attempts.

If the webhook cannot be delivered after 5 tries, the API will abandon attempts to deliver the notification and discard it.

Any discarded notifications are permanently lost and the system increments a counter to record that the message could not be delivered.

Disabled Webhooks

After a failed delivery, the system will attempt to send the next raised event in the ordinary way.

If delivery succeeds, the client’s failed-delivery counter is reset to 0.

If 100 consecutive webhook notifications fail delivery, the API takes the client to be inactive and disables the webhook, labelling it as Disabled.

Re-Enabling a Disabled Webhook

After a webhook has been designated Disabled, it must be re-enabled in order for the system to attempt to send it again.

To re-enable a webhook, update it’s status back to Active using Update a Dropship Webhook.

Securing Webhooks

To be able to receive notifications, client applications must expose an HTTP endpoint. Since webhook information can cause changes to your system, it is best practice for you to verify that the notification really came from iQmetrix, not from some other source.

To increase security, iQmetrix requires the webhook listener to use an SSL-enabled URL (HTTPS).

In addition, iQmetrix APIs digitally sign webhook notifications using a keyed-hash message authentication code created by hashing the request body with the HMAC-SHA256 hash function, using your client secret as the signing key. The signature is returned in the X-IQ-Signature header included in the notification request.

Your client system is responsible for verifying the signature before processing the notification.

OrderCreated Event

This event provides information about a newly created dropship order.

The body of the webhook payload is a JSON object that describes the Order that was created.

Example

{
    "Order": {
        "Id": "fbb17b9f-7982-4b73-b694-fc1d7fdc39ae",
        "SupplierId": 237372,
        "BillingCustomer": {
            "Id": "17124a01-47fd-4120-897d-4a419384b67c",
            "PrimaryName": "Jane",
            "FamilyName": "Doe"
        },
        "BillingCustomerAddress": {
            "Id": "e66f3c45-03e0-4d46-abf7-2b9342e8c210",
            "Country": "Canada",
            "CountryCode": "CA",
            "Locality": "Toronto",
            "Region": "Ontario",
            "RegionCode": "ON",
            "PostalCode": "H0H0H0",
            "PostOfficeBoxNumber": "",
            "StreetAddress1": "123 Main St",
            "StreetAddress2": "",
            "AttentionTo": "",
            "Email": "test@test.com",
            "Phone": "5555555555"
        },
        "ShippingCustomer": {
            "Id": "17124a01-47fd-4120-897d-4a419384b67c",
            "PrimaryName": "Jane",
            "FamilyName": "Doe"
        },
        "ShippingCustomerAddress": {
            "Id": "e66f3c45-03e0-4d46-abf7-2b9342e8c210",
            "Country": "Canada",
            "CountryCode": "CA",
            "Locality": "Toronto",
            "Region": "Ontario",
            "RegionCode": "ON",
            "PostalCode": "H0H0H0",
            "PostOfficeBoxNumber": "",
            "StreetAddress1": "123 Main St",
            "StreetAddress2": "",
            "AttentionTo": "",
            "Email": "test@test.com",
            "Phone": "5555555555"
        },
        "Seller": {
            "CompanyId": 14146,
            "LocationId": 14192,
            "LocationName": "Kiosk"
        },
        "Items": [
            {
                "CatalogId": "a183f1a9-c58f-426a-930a-9a6357db52ed",
                "Sku": "VAP-5532363",
                "Quantity": 1,
                "SellingPrice": 9.99,
                "Description": "",
                "Cost": 5.00,
                "Index": 1,
                "RequestedDate":"2018-06-14717:55:38.129Z",
                "SupplierReference": "{\"SomeJsonData\": \"ForProcessing\" }"
            }
        ],
        "ShippingMethod": "UPS",
        "ShippingMethodName": "",
        "ShippingCost": 5.52,
        "PoReference": "DDA2552205",
        "ShipToStore": false,
        "ShippingEntityId": 0,
        "ResubmissionReason": "",
        "ResubmittedDateUtc": "",
        "CreatedDate": "2020-05-07T17:17:30+0000",
        "OrderReference": ""
    },
    "EventDate": "2020-05-07T17:17:30+0000"
}

Payload Description

Property Description
Order (Order) Dropship Order
EventDate (DateTime) ISO 8601 UTC timestamp indicating when this event was created

Order

Name Description
Id (GUID) Identifier of the Dropship order
SupplierId (Integer) Identifier of the supplier
BillingCustomer (Customer) Customer to be billed for the order
BillingCustomerAddress (CustomerAddress) Address of the customer to be billed for the order
ShippingCustomer (Customer) Customer to ship the order to. If the order is being shipped directly to the customer, this comes from the ShippingCustomer object. If the order is being shipped to the store, this comes from the BillingCustomer object
ShippingCustomerAddress (CustomerAddress) Address to ship the order to. If the order is being shipped directly to the customer, this comes from the ShippingCustomerAddress object. If the order is being shipped to the store, this is the shipping address of the store selected. In this case, the AttentionTo field is automatically populated from the PrimaryName and FamilyName fields of the shipping customer. BusinessName is populated from the location’s DisplayName field. Phone number is populated from the contact methods of the billing customer. The phone number is set from the default phone number, if it exists; otherwise, the first phone number found is used
Seller Seller Information about the seller
Items (Array[OrderItems]) Information about the items in the order
ShippingMethod (String) Supplier shipping method
ShippingMethodName (String) Description for the supplier shipping method
ShippingCost (Decimal) Supplier shipping cost
PoReference (String) Identifier of an external order reference
ShipToStore (Boolean) Indicates whether the order is being shipped to the store or to the customer. This field is set to True if the ShippingEntityId field is greater than 0; False if ShippingCustomerCrmId and ShippingCustomerAddressCrmId are populated
ShippingEntityId (Integer) Identifier of the shipper entity. 0 if the order is being shipped to the customer and the Location identifier if the order is being shipped to the store
ResubmissionReason (String) The reason the order was resubmitted (if applicable)
ResubmittedDateUtc (DateTime) ISO 8601 UTC timestamp indicating when the order was resubmitted (if applicable)
CreatedDate (DateTime) ISO 8601 UTC timestamp indicating when the order was created
OrderReference (String) Generic field for storing information relevant to this order

OrderItem

Name Description
CatalogId (GUID) Identifier of the item in the Product Catalog
Sku (String) The supplier SKU for the item
Quantity (Integer) The number of items of this type in the order
SellingPrice (Decimal) The selling price of the item
Description (String) A description of the item
Cost (Decimal) The item cost
Index (Integer) Sort order for the items in the Order
RequestedDate (DateTime) A field for storing the provided delivery date
SupplierReference (String) A generic field for storing information relevant to this item

Customer

Name Description
Id (GUID) The customer identifier in the CRM service
PrimaryName (String) For a person, the first or given name. For an organization, business, or division, the full name
FamilyName (String) The customer’s surname or last name

CustomerAddress

Name Description
Id (GUID) Identifier of the address in the CRM service
Country (String) The country of this address
CountryCode (String) The ISO 3166-2 alpha-2 code for the country where this address is located
Locality (String) The locality (for example, city, town, or hamlet) of this address
Region (String) The state, province, or region of this address
RegionCode (String) The ISO 3166-2 alpha-2 Region code for the state or province where this address resides
PostalCode (String) The postal code/zip code for this address
PostOfficeBoxNumber (String) The post office box number for this address
StreetAddress1 (String) Line 1 of the street address
StreetAddress2 (String) Line 2 of the street address
AttentionTo (String) Attention To (Attn:)
Email (String) The contact email for this address
Phone (String) The contact phone number for this address

Seller

Name Description
CompanyId (Integer) Identifier of the selling company
LocationId (Integer) Identifier for the location
LocationName (String) The location name

OrderUpdated Event

This event provides information about a updated dropship order.

The body of the webhook payload is a JSON object that describes the Order that was updated.

Example

{
    "Order": {
        "Id": "8ac5e828-f046-4e9d-981b-98166d380127",
        "CompanyId": 14146,
        "SupplierId": 237372,
        "UpdatedDate": "2020-05-07T17:17:30+0000",
        "Items": [
            {
                "CatalogId": "a183f1a9-c58f-426a-930a-9a6357db52ed",
                "Sku": "VAP-5532363",
                "Quantity": 1,
                "Status": "Ordered",
                "TrackingInfo": "3423623666332426234233532623",
                "TrackingUrl": "https://www.ups.com",
                "ShippingProvider": "UPS",
                "Info": "",
                "Message": ""
            }
        ]

    },
    "EventDate": "2020-05-07T17:15:40+0000"
}

Payload Description

Name Description
Order (OrderStatusUpdate) Dropship Order Status Update
EventDate (DateTime) An ISO 8601 UTC timestamp indicating when this event was created

OrderStatusUpdate

Name Description
Id (GUID) Identifier of the Dropship order
CompanyId (Integer) Identifier of the company associated with the order
SupplierId (Integer) Identifier of the supplier
UpdatedDate (DateTime) An ISO 8601 UTC timestamp indicating when the order updated
Items (Array[ItemInformation] Products on the Order

ItemInformation

Name Description
CatalogId (GUID) Identifier for the product in the Catalog API
Sku (String) Supplier SKU (VendorSKU)
Quantity (Integer) Number of items of this type in the order
Status (String) Status. Possible values include: PendingSupplier, Ordered, Shipped, BackOrdered, Error, NotAvailable, PartiallyShipped, Cancelled, Resubmitted and Other
TrackingInfo (String) Tracking information for the shipment, updated by the supplier
TrackingUrl (String) Tracking url for the shipment, updated by the supplier
ShippingProvider (String) The shipping provider, updated by the supplier
Info (String) Additional information pertaining to the shipment, updated by the supplier
Message (String) A message about the order, updated by the supplier