Configuring Webhooks

For the triggers themselves, see Webhooks.

A webhook configuration names a destination URL, how to authenticate to it, which triggers it reports, and how it batches and retries. Create one or more with POST /webhook/settings. The body is an array, and every element becomes a new configuration:

POST /api/v1/webhook/settings
Content-Type: application/json

[
  {
    "Name": "ERP orders",
    "Active": true,
    "Authorization": {
      "Basic": {
        "Username": "gains-webhooks",
        "Password": "Vq7#pL2m-Xr9"
      }
    },
    "Url": "https://erp.example.com/gains/webhooks",
    "PayloadMaxItems": 100,
    "PayloadInterval": 60,
    "Triggers": {
      "POSubmit": {
        "Enabled": true,
        "Filter": "ReceivingLocation IN ('CHI01', 'DC-EAST')"
      },
      "TOSubmit": {
        "Enabled": true
      },
      "TaskStatusUpdate": {
        "Enabled": true,
        "Filter": "Status IN ('Completed', 'Failed', 'RejectedFailedProcessing')"
      }
    },
    "RetryHandling": {
      "Attempts": 3,
      "Gap": 10
    },
    "FieldNamingConvention": "PASCAL_CASE"
  }
]

The response returns each new configuration with the Id you use to change it later. Secrets are masked:

{
  "Status": "success",
  "Reason": "New webhook(s) configured. Any updates to a webhook configuration should use the PUT method.",
  "TotalConfigurations": 1,
  "NewConfigurations": [
    {
      "Id": 3,
      "Name": "ERP orders",
      "Active": true,
      "Authorization": {
        "Basic": {
          "Username": "gains-webhooks",
          "Password": "******"
        }
      },
      "Url": "https://erp.example.com/gains/webhooks",
      "PayloadMaxItems": 100,
      "PayloadInterval": 60,
      "Triggers": {
        "POSubmit": {
          "Enabled": true,
          "Filter": "ReceivingLocation IN ('CHI01', 'DC-EAST')"
        },
        "TOSubmit": {
          "Enabled": true,
          "Filter": null
        },
        "TaskStatusUpdate": {
          "Enabled": true,
          "Filter": "Status IN ('Completed', 'Failed', 'RejectedFailedProcessing')"
        }
      },
      "RetryHandling": {
        "Attempts": 3,
        "Gap": 10
      },
      "ConfigurationMode": "v2",
      "PreferencesUpdated": "2026-10-21 09:42:17",
      "FieldNamingConvention": "PASCAL_CASE"
    }
  ]
}

When a request enables InventoryPolicyUpdate, ForecastWeeklyUpdate or ForecastMonthlyUpdate for the first time, Reason adds that notifications for the trigger may take up to 15 minutes to begin.

Managing configurations

POST always adds configurations; it never changes an existing one.

• PUT replaces the whole configuration. A setting you leave out takes its default, Triggers left out means no triggers, and Authorization left out removes authorization. Send every secret again.
• PATCH changes only what you send. Everything you omit keeps its stored value, secrets included, so you can change a URL or a trigger without resending credentials. Triggers and RetryHandling are replaced as a whole when present, so send every trigger you want to keep.

{
  "Active": false
}

Settings

What PayloadMaxItems counts depends on the trigger: orders for the order triggers, SKU-locations for the inventory policy and forecast triggers, and task status changes for TaskStatusUpdate.

The read-only fields of a configuration are Id, ConfigurationMode and PreferencesUpdated, the time it was last changed.

Authorization

Authorization takes exactly one of four schemes, or {} for none.

Header and Basic send the same credential with every delivery, so you rotate it yourself. The OAuth 2.0 schemes send a short-lived token that GAINS Connect renews before it expires. Both OAuth 2.0 schemes have further optional fields for identity providers that need them. OAuth 2.0 Webhook Destinations describes each field, how tokens are obtained and renewed, and gives examples for Microsoft Entra ID and Oracle NetSuite.

Secrets (Value, Password, ClientSecret, PrivateKey) are stored encrypted and never returned:

• A read shows each secret as ******. Sending ****** back is refused, so use PATCH and leave the secret out to keep it.
• In a PATCH, the same scheme member changes only the fields you send. Naming a different scheme replaces the old one and needs all of its required fields, and {} removes authorization.
• A secret that reads ******(re-enter) can no longer be used. Deliveries for that configuration fail until you send the secret again with PATCH.

Destination URL

Use an https address that can be reached from the internet, and point Url at the final address: redirects are not followed. Put credentials in Authorization, never in the URL.

Multiple configurations

You can have several configurations, each with its own URL, authorization, triggers, filters and batching. Use them to send the same event to more than one system, or to split one trigger's records between destinations with filters. For example, two configurations that both enable InventoryPolicyUpdate, one with the filter LocationCode IN ('CHI01', 'DC-EAST') and the other with LocationCode NOT IN ('CHI01', 'DC-EAST'), divide the policy changes between two systems.

Configurations deliver independently: a destination that is down delays only its own payloads.