Webhooks

GAINS publishes webhooks for specific events to allow for real-time integration to client endpoints

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)

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
• 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 or WO's. If GAINS core has a combination of PO's, TO's and WO's waiting to be sent to you, PO's will always be sent first. Thereafter, the remaining of TO's and WO's will be sent based on the one that entered the queue first.

Successive payloads will always respect the PayloadMaxItems and PayloadInterval parameters.

Webhook Sample

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

JSON

{
  "DataType": "purchase_order",
  "Data": [
    {
      "TrackingNumber": 123,
      "ShippingLocation": "ABC",
      "ReceivingLocation": "LF500",
      "ReleaseDate": "2024-05-21",
      "RequestedDeliveryDate": "2024-06-21",
      "SubmittedBy": "[email protected]",
      "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:

Text

{
  "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