Webhooks

Webhook subscriptions allow for automated notifications to your designated systems on the occurrence of certain triggers in GAINS.

The current available webhook triggers are:

Submission of Purchase Orders (PO's)
Submission of Transfer Orders (TO's)
Submission of Work Orders (WO's)
Changes to SKU-Location's inventory policy data

The following webhook triggers will be introduced early 2025:

Changes to a SKU's forecast data
Changes to task status

Webhook notifications are issued based on the settings you have defined for the following:

Payload Max Items - allows you to limit the number of records produced in the payload
- For replenishment triggers such as new purchase, transfer and work orders, this represents the number of orders
- For forecast and inventory update triggers, this represents the number of SKU-Locations
Payload Interval - define the gap (in seconds) between notifications
Retry Attempts - after a failed attempt, specify the number of times we should attempt to re-send a payload
Retry Gap - specify the time (in minutes) between retry attempts

Webhook Behavior

A single webhook notification will only contain one record type - either PO's, TO's, WO's or SKU-Location inventory policy.

The queue processing rules are as follows:

Messages are processed in the order they enter the queue (FIFO)
When processing a message type, the system will include as many records of that type as possible up to PayloadMaxItems
Once a batch is full or no more records of that type are available, we move to the next message type in the queue
Any remaining records of the same type will be processed in subsequent queue iterations

Example - let's say we have the following items in the queue, starting from the first to enter the queue:

1. 10 POs (first messages in queue)
2. 12 TOs
3. 2 WOs
4. 10 POs
5. 50 SKULs (last messages in queue)

Let's assume that the PayloadMaxItems attribute is set to 15.

All successive payloads will respect PayloadInterval parameter.

Webhook Sample

The following sample shows a webhook payload with a single purchase order and multiple line items:

{
  "DataType": "purchase_order",
  "Data": [
    {
      "TrackingNumber": 123,
      "ShippingLocation": "ABC",
      "ReceivingLocation": "LF500",
      "ReleaseDate": "2024-05-21",
      "RequestedDeliveryDate": "2024-06-21",
      "SubmittedBy": "john@client.com",
      "Documentation": "Comments",
      "ContactName": "John Doe",
      "ContactEmail": "",
      "ShipMethod": "land",
      "Address1": "123 Any St",
      "Address2": null,
      "Address3": null,
      "City": "Chicago",
      "State": "IL",
      "PostalCode": "N",
      "Country": "Y",
      "LineItems": [
        {
          "ItemCode": "938939",
          "ItemDescription": "Widget Small",
          "Quantity": 1,
          "Cost": 10,
          "LineComment": null,
          "UpdatedTime": "2024-05-21 11:00:00",
          "BuyerCode": "Jack",
          "ApprovalCode": "U",
          "ApprovedBy": "finley"
        },
        {
          "ItemCode": "938940",
          "ItemDescription": "Widget Large",
          "Quantity": 10,
          "Cost": 100,
          "LineComment": null,
          "UpdatedTime": "2024-05-21 11:00:00",
          "BuyerCode": "Jack",
          "ApprovalCode": "U",
          "ApprovedBy": "finley"
        }
      ]
    }
  ]
}

Note that, a single payload can contain multiple order entities and this would be reflected within the Data array:

{
  "DataType": "purchase_order",
  "Data": [
    {"TrackingNumber": 123, ...}, 
    {"TrackingNumber": 124, ...}, 
    {"TrackingNumber": 125, ...}
  ]
}

Webhook Timeouts

Please note that webhooks are designed to live for 90 seconds. This means:

Request Timeout: If your server does not respond within 90 seconds, the webhook delivery attempt will be considered a failure
Retries: If a delivery attempt fails (e.g., your server returns a non-2xx status code or times out), our system will retry the delivery according to a retry process. All retries will also adhere to the 90-second lifespan

Resending a Webhook

You may request a re-transmission of a webhook based on existing webhook Url and Authorization attributes. Re-sending a webhook can be done on the basis of an entire payload WebhookId or partial payload based on a TrackingNumber (i.e. order object) contained in a webhook.

Note:

Webhook re-send requests will be respected even if the trigger for that type of webhook is disabled in webhook settings
Please be aware that re-sending webhooks can result in duplicate data. Make sure your systems are equipped to manage potential duplicates effectively

Inventory Policy Change Webhook

A webhook is issued when any of the following attributes have been modified in GAINS either via user action in the UI or by a background process:

AdjustedOrq
MinimumOrq
IncrementalOrq
Rsq
RsqOverride
CalcSs
AdjustedSs
SsOverride
ServiceLevel
ServiceLevelMinimum
InventoryClass
StockIndicator
LeadTime