Receiving Webhooks

This page is for whoever builds the endpoint that receives GAINS webhooks. It covers the request GAINS Connect sends, how to answer it, timeouts, duplicates and ordering, and how to find out why a delivery failed. To set up a webhook in the first place, see Webhooks.

The request you receive

Every webhook is an HTTP/1.1 POST to the Url of a webhook configuration, with a JSON body:

POST /gains/webhooks HTTP/1.1
Host: erp.example.com
Content-Type: application/json
Content-Length: 1834
Authorization: Basic Z2FpbnMtd2ViaG9va3M6VnE3I3BMMm0tWHI5

{
  "DataType": "purchase_order",
  "Data": [
    {
      "TrackingNumber": 4821,
      "ReceivingLocation": "CHI01"
    }
  ]
}

The body is UTF-8 JSON in the envelope described in Payload format: DataType names the subject and Data holds the records. Its field names follow the configuration's FieldNamingConvention.

The Authorization header for each scheme:

A webhook carries no signature, event ID or delivery ID header. Check the Authorization header on every request to decide whether to trust it, and identify the records from the payload itself (see Duplicates).

Answering a webhook

What your URL answers decides whether the delivery succeeded:

• Answer 2xx once you have stored the payload. Anything you answer after that is your own processing, not delivery.
• Never answer with a redirect. Point Url at the exact address that accepts the POST.
• The response body is not read. The start of it, and your response headers, are kept so you can see them in webhook history.

How failed deliveries are retried, and how a failing payload holds back the ones behind it, is described in Retries.

Timeouts

Answer within 90 seconds. Otherwise the delivery has failed and is recorded with status code 504.

Respond fast and process asynchronously:

1. Check the Authorization header.
2. Store the body as received, for example on a message queue or in a staging table.
3. Answer 200 or 202.
4. Process the stored payload separately.

A payload can hold up to PayloadMaxItems records, up to 500, so a large order payload can take a few megabytes. Make sure any gateway or proxy in front of your endpoint accepts a body of that size and does not time out sooner than your own processing.

Duplicates

GAINS Connect delivers each payload at least once, not exactly once. You can receive the same records more than once when:

• You processed a payload but answered too late, or answered something other than 2xx. The payload is retried.
• A payload is resent with POST /webhook/resend, by you or by GAINS support.

Make processing a record twice harmless. Neither the request nor the payload carries a delivery ID, so key on the fields that identify each record:

Write records as inserts-or-updates on those keys rather than as plain inserts, and do not let an older version overwrite a newer one. The weekly and monthly forecast triggers share DataType forecast; tell them apart by the length of their buckets, as Webhook Payload Samples describes.

🚧

Test payloads are made up

POST /webhook/test sends sample records to your real URL. Make sure a test cannot create orders or change data in your production system, for example by testing against a non-production URL first.

Ordering

Do not rely on the order in which payloads arrive. A resent payload arrives after newer data for the same records, and several configurations pointing at the same URL send to it in parallel, so your endpoint must accept concurrent requests.

Your endpoint

• Serve https with a certificate from a public certificate authority. Otherwise delivery fails, and webhook history records it as 503.
• Do not rely on headers other than those listed above.

The full rules for the Url setting are in Destination URL.

Troubleshooting

Reading webhook history

GET /webhook/history lists every try of every delivery for the last 30 days. To see today's failures:

GET /api/v1/webhook/history?Status=failed&SearchDateStart=2026-10-21 00:00:00

Each entry shows the HttpStatusCode and Response of one try. When your URL answered, Response holds its Headers and the start of its Body. When it could not answer, GAINS Connect records one of these codes itself, and Response has no headers from your server:

Your own server can answer 502, 503 or 504 too, for example from a gateway in front of it. Its headers in Response tell the two apart.

{
  "WebhookId": 98412,
  "ConfigurationId": 3,
  "IssuedAt": "2026-10-21 09:15:02",
  "ResponseReceivedAt": "2026-10-21 09:16:32",
  "IssuedTo": "https://erp.example.com/gains/webhooks",
  "Authorization": "Basic",
  "Status": "failed",
  "HttpStatusCode": 504,
  "Attempt": 1,
  "Trigger": "po_submit",
  "Response": {
    "Headers": {},
    "Body": null,
    "StatusCodeValue": 504,
    "StatusCode": "GATEWAY_TIMEOUT"
  }
}

The filters and fields of webhook history, and how to read a payload, are in Webhook history.

A secret reads ******(re-enter)

When GET /webhook/settings shows a secret as ******(re-enter) instead of ******, the stored secret can no longer be used. Every delivery for that configuration then fails with 502, and nothing reaches your URL:

{
  "error": "credential_must_be_re_entered",
  "errorDescription": "The stored credential for this webhook can no longer be decrypted and must be re-entered."
}

Send the secret again with PATCH /webhook/settings/{ConfigurationId}, naming the same scheme and only the secret:

{
  "Authorization": {
    "Basic": {
      "Password": "Vq7#pL2m-Xr9"
    }
  }
}

Testing, resending and discarding

To test a configuration, resend a dropped payload or see and discard what is queued, see Delivery & Recovery.

Related

• Webhooks — configuration, triggers, filters, delivery and monitoring.
• Webhook Payload Samples — the payload of each trigger.
• OAuth 2.0 Webhook Destinations — authenticating to your URL with an identity provider.
• Errors & Exceptions — the error body of the webhook endpoints.