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:

• The event name
• The ID of the entity that the event pertains to (for example, a company or supplier)
• The specific contents of the event

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

Order

OrderItem

Customer

CustomerAddress

Seller

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

OrderStatusUpdate

ItemInformation