WEBHOOKS BASICS

What Is a Webhook?

A webhook is essentially an HTTP call-back from a source system to a client system. When a change occurs, the source system pushes a notification to the client system.

Webhooks provide a simple way for the API to notify you when specific events or updates have occurred. They are designed to eliminate the need to poll the application to see whether anything has changed.

Each API has certain events that support webhooks. These vary with the API. To be notified when such an event occurs, you subscribe a webhook for each event type you want to receive and the URL that the event notifications should be sent to.

Creating a Webhook

To create a webhook for an API, you POST a request to its webhooks endpoint with the event type and the URL of an endpoint that will “listen” for webhook notifications and process them appropriately. This “listener” endpoint must be implemented on the client system’s web server. The POST webhooks request registers your listener URL with your entity details and the requested event type so that your listener endpoint will start to receive HTTP POST API callbacks every time a relevant event is issued.

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. An HTTP 2xx response tells the API that the notification was successfully received.

The API interprets any response codes outside the 2xx range to mean that you did not receive the webhook. Any other 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 30-second intervals to a maximum of 5 attempts. If the webhook cannot be delivered after 5 tries, the API abandons attempts to deliver the notification and discards 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 5 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. You do this by setting its status back to Active (using a PUT to the webhook endpoint).

Securing Webhooks

To be able to receive notifications, client applications must expose an HTTP endpoint over the Internet. 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.

DROPSHIP AND WEBHOOKS

Dropship webhooks are designed to help suppliers track orders by notifying for new and updated orders. To use Dropship webhooks effectively, keep the following in mind.

Order Status

Every order has a status, which updates throughout the lifecycle of the order. The list of status values that are possible for orders are shown here. If the order status values in your system do not have a suitable correlate in the order status values provided by iQmetrix, you can use the 8 (Other) status and provide your own label in the Message property.

When the Dropship order is created, the order is automatically assigned a status of 0 (PendingSupplier) by the Dropship service.

It’s important for you, the supplier, to note that when you receive the order in your system it is your responsibility to update the status of the order to 1 (Ordered). Updating the status of an order updates the status of each item in the order.

Avoiding Duplicate Orders

The iQmetrix architecture is distributed, and to ensure that messages are never lost the system employs an “at-least-once” delivery mechanism. “At-least-once” means that message delivery is reliable; however, occasionally messages may be duplicated.

To avoid processing the same order more than once, your system should track the identifier for the Dropship order. In the Order Notifications Feed, this information is captured in the order-created.order-id field. In the Dropship Webhooks OrderCreated event, this information is cpatured in the Id property of the Order resource.

BASE URLS

Demo Base URL: https://dropshipdemo.iqmetrix.net/v1
Production Base URL: https://dropship.iqmetrix.net/v1
Webhooks URI: /Entities({entityId})/Events({eventName})/Webhooks

RESOURCES

Dropship has resources defined for both the webhook itself and for the events that support webhooks.

Webhook

This resource reports on the current status of a webhook. Included is information about the webhook itself.

Name Description
id (GUID) The identifier of the webhook.
owner (String) The API that has registered the webhook; in this case, Dropship.
clientKey (String) The client key.
eventEntityId (Integer) The entity for which notifications will be sent.
description (String) A description of the webhook.
notificationUrl (String) Required. The URL where notifications should be sent. The string is validated to ensure it is a valid absolute HTTPS URL.
status (Enum) Required. The status of the webhook. Supported values are Active (Make the webhook active) and InActive (Deactivate the webhook).
event (String) The event being requested. Supported values are OrderCreated and OrderUpdated.

OrderCreated Event

This event reports on the status of an order, or of individual items in that order. The OrderCreated event returns information from the Order, OrderItem, Customer, CustomerAddress, OrderItem, and Seller resources.

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

Order

Name Description
Id (GUID) The identifier of the Dropship order.
SupplierId (Integer) The identifier of the supplier.
BillingCustomer (Customer) The customer to be billed for the order.
BillingCustomerAddress (CustomerAddress) The address of the customer to be billed for the order.
ShippingCustomer (Customer) The customer to ship the order to.
- If the order is being shipped directly to the customer, this is the ShippingCustomerCrmId field from the PendingOrder object.
- If the order is being shipped to the store, this is the BillingCustomerCrmId field from the PendingOrder resource.
ShippingCustomerAddress (CustomerAddress) The address to ship the order to.
- If the order is being shipped directly to the customer, this is the ShippingCustomerAddressCrmId field from the PendingOrder object.
- If the order is being shipped to the store, this is the ShippingEntityId field from the PendingOrder resource. 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) The supplier shipping method.
ShippingMethodName (String) A description for the supplier shipping method.
ShippingCost (Decimal) The supplier shipping cost.
PoReference (String) The 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) The identifier of the shipper. This is 0 if the order is being shipped to the customer; if the order is being shipped to the store, this is the Location identifier of the store.
ResubmissionReason (String) The reason the order was resubmitted (if applicable).
ResubmittedDateUtc (DateTime) An ISO 8601 UTC timestamp indicating when the order was resubmitted (if applicable).
CreatedDate (DateTime) An ISO 8601 UTC timestamp indicating when the order was created.
OrderReference (String) A generic field for storing information relevant to this order.

OrderItem

Name Description
CatalogId (GUID) The 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) The 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) The identifier of the selling company.
LocationId (Integer) The identifier for the location in the Company’s CompanyTree data structure.
LocationName (String) The location name.

OrderUpdated Event

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) The identifier of the Dropship order.
CompanyId (Integer) The identifier of the company generating the order.
SupplierId (Integer) The identifier of the supplier.
UpdatedDate (DateTime) An ISO 8601 UTC timestamp indicating when the order updated.
Items Array[ItemInformation] An array of the items that have been updated.

ItemInformation

Name Description
CatalogId (GUID) The 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.
Status (String) The item status. Supported values are shown in Item Status Values
TrackingInfo (String) The tracking information for the shipment. Updated by the supplier.
TrackingUrl (String) The 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.

Item Status Values

REQUESTS

Required Headers

The following headers are required for all requests

Name Value
Authorization Bearer {AuthToken}
Accept application/json
Content-Type application/json

Create a Webhook

Registers a webhook for a Dropship event.

Request


POST /Entities({entityId})/Events({eventName})/Webhooks

Example Request

POST /Entities(12345)/Events(OrderCreated)/Webhooks
Authorization: Bearer cn389ncoiwuencr
Accept: application/json
Content-type: application/json

{
  "clientKey": "clientService",
  "eventEntityId": 12345,
  "description": "Webhook Description",
  "notificationUrl": "https://www.iqmetrix.com",
  "status": "Active"
}

Path Parameters

Name Description
entityId (Integer) The id of the entity associated with the webhook.
eventName (Enum) The name of the event associated with the webhook. Supported values are OrderCreated and OrderUpdated.

Request Parameters

Name Description
clientKey (String) Required. Client Key.
EventEntityId (Integer) Required. Event Entity Id.
description (String) Required, but may be null. Description of the webhook.
notificationUrl (String) Required. The URL where notifications should be sent. The string is validated to ensure it is a valid absolute HTTPS URL.
status (Enum) Required. The status of the webhook. Supported values are Active (Make the webhook active) and InActive (Deactivate the webhook).

Response

Example Response

HTTP 201 Content-Type: application/json
{
    "id": "e893c644-ef90-44ca-b3cf-091599e051e9",
    "owner": "Dropship",
    "clientKey": "ClientService",
    "eventEntityId": 12345,
    "description": "string",
    "notificationUrl": "https://www.iqmetrix.com",
    "status": "Active",
    "event": " OrderCreated"
}

A successful request returns a 201 (Created) response code with the information for the webhook in the body of the response. For a description of parameters defined for the Webhook resource, see Webhook.

Get a Webhook

Retrieves a webhook for a Dropship event.

Request


GET /Entities({entityId})/Events({eventName})/Webhooks({id})

Example Request

GET /v1/Entities(12345)/Events(OrderCreated)/Webhooks(e893c644-ef90-44ca-b3cf-091599e051e9)
Authorization: Bearer cn389ncoiwuencr
Accept: application/json
Content-type: application/json

Path Parameters

Name Description
entityId (Integer) The id of the entity associated with the webhook.
eventName (Enum) The name of the event associated with the webhook. Supported values are OrderCreated and OrderUpdated.
id (GUID) The identifier of the webhook you want to retrieve.

Request Parameters

None.

Response

Example Response

HTTP 200 Content-Type: application/json
{
  "id": "e893c644-ef90-44ca-b3cf-091599e051e9",
  "owner": "Dropship",
  "clientKey": "clientService",
  "eventEntityId": 12345,
  "description": "",
  "notificationUrl": "https://www.iqmetrix.com",
  "status": "Active",
  "event": " OrderCreated"
}

A successful request returns a 200 (OK) response code with the information for the webhook in the body of the response. For a description of parameters defined for the Webhook resource, see Webhook.

Get All Webhooks

Retrieves all webhooks registered for a given event.

Request


GET /Entities({entityId})/Events({eventName})/Webhooks

Example Request

GET /v1/Entities(12345)/Events(OrderCreated)/Webhooks
Authorization: Bearer cn389ncoiwuencr
Accept: application/json
Content-type: application/json

Path Parameters

Name Description
entityId (Integer) The id of the entity associated with the webhook.
eventName (Enum) The name of the event associated with the webhook. Supported values are OrderCreated and OrderUpdated.

Request Parameters

None.

Response

Example Response

HTTP 200 Content-Type: application/json
[
  {
    "id": "e893c644-ef90-44ca-b3cf-091599e051e9",
    "clientKey": "clientService",
    "eventEntityId": 12345,
    "description": "",
    "notificationUrl": "https://www.iqmetrix.com",
    "status": "Active",
  },
  {
    "id": "bb856840-0034-4977-b5ba-dfbed9fb079d",
    "clientKey": "clientService",
    "eventEntityId": 23456,
    "description": "",
    "notificationUrl": "https://www.iqmetrix.com",
    "status": "Active",
  }
]

A successful request returns a 200 (OK) response code with array of the found webhooks in the body of the response.

If the request is valid but no webhooks are found, system returns a 404 (Not found) response.

For a description of parameters defined for the Webhook resource, see Webhook.

Update a Webhook

Allows you to update a webhook; for example to deactivate, reactivate, or re-enable it.

Request


PUT /Entities({entityId})/Events({eventName})/Webhooks({id})

Example Request

PUT /Entities(12345)/Events(OrderCreated)/Webhooks(e893c644-ef90-44ca-b3cf-091599e051e9)
Authorization: Bearer cn389ncoiwuencr
Accept: application/json
Content-type: application/json

{
  "description": "Updated Description",
  "notificationUrl": "https://www.iqmetrix.com",
  "status": "Active"
}

Path Parameters

Name Description
entityId (Integer) The id of the entity associated with the webhook.
eventName (Enum) The name of the event associated with the webhook. Supported values are OrderCreated and OrderUpdated.
id (GUID) The identifier of the webhook you want to update.

Request Parameters

Name Description
description (String) Required, but may be null. Description of the webhook.
notificationUrl (String) Required. The URL where notifications should be sent. The string is validated to ensure it is a valid absolute HTTPS URL.
status (Enum) Required. The status of the webhook. Supported values are Active (Make the webhook active) and InActive (Deactivate the webhook).

Response

Example Response

HTTP 200 Content-Type: application/json
{
  "id": "e893c644-ef90-44ca-b3cf-091599e051e9",
  "owner": "Dropship",
  "clientKey": "clientService",
  "eventEntityId": 12345,
  "description": "",
  "notificationUrl": "https://www.iqmetrix.com",
  "status": "Active",
  "event": " OrderCreated"
}

A successful request returns a 200 (OK) response code with the updated information for the webhook in the body of the response. For a description of parameters defined for the Webhook resource, see Webhook.

Delete a Webhook

Deletes a Dropship webhook.

Request


DELETE /Entities({entityId})/Events({eventName})/Webhooks({id})

Example Request

DELETE /Entities(12345)/Events(OrderCreated)/Webhooks(e893c644-ef90-44ca-b3cf-091599e051e9)
Authorization: Bearer cn389ncoiwuencr
Accept: application/json
Content-type: application/json

Path Parameters

Name Description
entityId (Integer) The id of the entity associated with the webhook.
eventName (Enum) The name of the event associated with the webhook. Supported values are OrderCreated and OrderUpdated.
id (GUID) The identifier of the webhook you want to delete.

Request Parameters

None.

Response

Example Response

HTTP 200 Content-Type: application/json

A successful request returns a 200 (OK) response code. For a description of parameters defined for the Webhook resource, see Webhook.

ERRORS

Error Code Name Description
HTTP 400 Bad Request The request was somehow incorrect or invalid. Check that all required parameters have been provided.
HTTP 401 Unauthorized The user making the request is not authenticated. The most common reason for this is that the access token used in the request has expired. Generate a new access token (or refresh the existing token) using the Authentication API.
HTTP 403 Forbidden The user making the request is authenticated, but does not have permission to access the requested resource. Make sure that the user making the request has appropriate permissions.
HTTP 404 Not Found The requested resource cannot be found. Ensure that event name in the request is correct.
Was this page helpful?