Webhooks

Overview

Samtec's webhooks push a lightweight HTTP POST to your endpoint whenever one of four events happens: an order line's status changes, a shipment ships, a tracked opportunity updates, or a part's stock quantity changes. Each message carries just enough to identify what happened — an order number, a part number, and so on — plus a dataUrl you can call to fetch the full record from the matching Samtec API.

Unlike the rest of this portal, webhooks are inbound to you: Samtec calls your endpoint, not the other way around. There's no Reference page or playground for this section — it's prose-only.

Supported Events

Subscription name	`eventName` in payload	Trigger
`order.statuschanged`	`Order Status Changed`	An order line's status changes. `received` and `on hold` statuses never trigger a webhook.
`order.shipment`	`Advanced Shipping Notification`	A shipment is picked up by the carrier. One message per order line in the shipment — never a batch.
`opportunity.updated`	`Opportunity Updated`	A change to an open opportunity's interval, part configuration, or purchaser data, once it has at least one completed part configuration.
`part.stockquantitychanged`	`Part Stock Quantity Changed`	A part's stock quantity changes. Sent to every organization subscribed to this event, not scoped to a specific order or customer.

The subscription name (left column) is what you tell Samtec you want to receive — see Setting Up Webhooks. The eventName (middle column) is what actually shows up in the payload you receive.

Who Receives Events

You receive an event only if your organization is subscribed to it and the record that changed is tied to you:

Order events (order.statuschanged, order.shipment). For a sales order, the event goes to the bill-to customer. For no-charge orders and sample orders, it goes to the ship-to customer. If the customer that applies isn't subscribed, no one is notified. For example, a customer that is only the ship-to on a sales order doesn't receive it.
opportunity.updated. The opportunity's design customer, and the primary and secondary purchasers on each completed part configuration, each receive their own message if they're subscribed.
part.stockquantitychanged. Every subscribed organization receives it.

Payload Reference

Common envelope

Every webhook POST body has this shape:

{
  "companyName": "Samtec",
  "traceIdentifier": "8f14e45f-ceea-467e-bd3f-11a2c9d7e001",
  "eventName": "Order Status Changed",
  "eventTime": "2026-08-14T09:32:07.481Z",
  "dataUrl": "https://api.samtec.com/orders/v1/history?orderId=4512389&mfgLineNumber=1&includeCancelledLines=true",
  "keys": { }
}

eventName identifies which event this is — see the table above for the value each subscription sends.
dataUrl points back into the matching Samtec API for the full record. Call it with the same Authorization: Bearer <token> and client-app-name headers described in Authentication — the webhook payload itself carries no API token.
Every value inside keys is a JSON string, including ones that look numeric (a stock quantity, a line number). Parse them as strings, not numbers.
The envelope's own field names are camelCase (companyName, traceIdentifier, eventName, eventTime, dataUrl, keys) — but the field names inside keys (OrderNumber, StockQuantity, and so on below) stay PascalCase.

`order.statuschanged` — Order Status Changed

keys: OrderNumber, LineNumber, Status, PurchaseOrderNumber

{
  "companyName": "Samtec",
  "traceIdentifier": "8f14e45f-ceea-467e-bd3f-11a2c9d7e001",
  "eventName": "Order Status Changed",
  "eventTime": "2026-08-14T09:32:07.481Z",
  "dataUrl": "https://api.samtec.com/orders/v1/history?orderId=4512389&mfgLineNumber=1&includeCancelledLines=true",
  "keys": {
    "OrderNumber": "4512389",
    "LineNumber": "1",
    "Status": "Shipped",
    "PurchaseOrderNumber": "PO-88214-A"
  }
}

`order.shipment` — Advanced Shipping Notification

keys: OrderNumber, LineNumber, PurchaseOrderNumber

One message per order line in the shipment — a shipment covering several lines produces several webhook calls, not one call with an array of lines.

{
  "companyName": "Samtec",
  "traceIdentifier": "2c9a71b0-4e13-4f8a-9c22-7d9b6a441a77",
  "eventName": "Advanced Shipping Notification",
  "eventTime": "2026-08-14T14:05:22.104Z",
  "dataUrl": "https://api.samtec.com/orders/v1/history?orderId=4512389&mfgLineNumber=1&includeShipments=true",
  "keys": {
    "OrderNumber": "4512389",
    "LineNumber": "1",
    "PurchaseOrderNumber": "PO-88214-A"
  }
}

`opportunity.updated` — Opportunity Updated

keys: DesignCustomer, EffectiveDate, ExpirationDate

EffectiveDate and ExpirationDate are ISO 8601 timestamps in UTC, not plain dates.

{
  "companyName": "Samtec",
  "traceIdentifier": "a5d8e6c2-19b7-4a3e-8f60-3e9d1c774b2e",
  "eventName": "Opportunity Updated",
  "eventTime": "2026-08-14T11:18:45.902Z",
  "dataUrl": "https://api.samtec.com/quotes/v1?opportunityId=771234&includeCurrentOnly=false&pageNumber=1",
  "keys": {
    "DesignCustomer": "Acme Robotics Inc.",
    "EffectiveDate": "2026-08-14T04:00:00Z",
    "ExpirationDate": "2026-11-14T23:59:59.999Z"
  }
}

`part.stockquantitychanged` — Part Stock Quantity Changed

keys: Part, StockQuantity

Sent to every organization subscribed to this event — it isn't scoped to a specific order or customer, so you'll receive it for any part you subscribe to, whether or not you currently have an open order for it.

{
  "companyName": "Samtec",
  "traceIdentifier": "6b3f9d21-7a44-4e88-b0d5-2f1c9a83e5d0",
  "eventName": "Part Stock Quantity Changed",
  "eventTime": "2026-08-14T06:50:12.330Z",
  "dataUrl": "https://api.samtec.com/catalog/v3/TSW-110-08-T-D?includeRelatedParts=false&isoCurrencyCode=USD",
  "keys": {
    "Part": "TSW-110-08-T-D",
    "StockQuantity": "18500"
  }
}

Authentication

Samtec doesn't sign webhook payloads — there's no HMAC signature or similar cryptographic scheme to verify. Verification is a shared credential you and Samtec agree on when setting up the subscription: Samtec attaches it to every call, and you confirm the value matches what you configured.

That credential is delivered one of two ways, depending on what you choose during setup:

Header or query string, static value. Samtec attaches a header or query parameter (name and value agreed on during setup) to every request, verbatim. Check that its value matches what you provided.
Header, OAuth 2.0 client credentials. If you give Samtec a token endpoint, client ID, and client secret, Samtec fetches an access token via the client credentials grant and sends it as <your header name>: bearer <token> (lowercase bearer). Tokens are cached for up to 59 minutes per organization before being refreshed. If your endpoint returns 401 in this mode, Samtec refreshes the token once and retries that single delivery before falling back to normal redelivery behavior.

Query-string delivery is always the raw value or token, with no bearer prefix — the prefix only applies to header delivery in OAuth mode.

Your endpoint URL must use HTTPS. Nothing in the delivery path itself technically rejects a non-HTTPS URL, but it's required — don't provide an http:// endpoint when setting up a subscription.

Setting Up Webhooks

To subscribe, provide the webhook team with:

Your endpoint URL — where Samtec should POST events.
Which events to subscribe to — one or more subscription names from the Supported Events table.
Your auth preference — either a header or query-string name and static value, or, for OAuth, a token endpoint, client ID, and client secret.

Submit this the same way you request an API token (see Onboarding) — email apionboarding@samtec.com with the details above. There's no self-serve setup form; webhook subscriptions are configured by the team on your behalf.

On your end, your endpoint should:

Accept an HTTP POST with a JSON body shaped like the payload reference above.
Respond with any 2xx status — Samtec's sender treats any 2xx response as success, not specifically 200.
Respond within 30 seconds.

Reliability and Retries

Every delivery attempt — success or failure — is logged with its full request, response, and timing, so Samtec's team can look up what was sent and how your endpoint responded.

A 2xx response counts as delivered; anything else, including no response at all, counts as a failure.
Failed deliveries are retried and redelivered automatically a limited number of times before being dequeued.
Delivery is at-least-once, not exactly-once. Build your endpoint to be idempotent — for example, dedupe on traceIdentifier, or on the combination of eventName + keys + eventTime — rather than assuming you'll only ever see a given event once.
The one exception to standard retry behavior: an OAuth-authenticated endpoint that returns 401 gets one immediate token-refresh-and-retry before anything reaches the redelivery queue (see Authentication).

Troubleshooting

Symptom	Likely cause	What to check
Not receiving any events	Not subscribed to that event, or your endpoint/auth is misconfigured	Confirm your subscription list and endpoint URL/auth with apionboarding@samtec.com.
Receiving the same event more than once	Expected — delivery is at-least-once	Dedupe on `traceIdentifier` rather than assuming single delivery.
A field that looks like a number won't parse	`keys` values are always JSON strings	Parse every `keys` field as a string, even ones like `StockQuantity` or `LineNumber`.
`dataUrl` call returns `401` or `403`	`dataUrl` requires your normal API bearer token, not the webhook's own auth credential	Call `dataUrl` with the `Authorization` and `client-app-name` headers described in Authentication.
Getting `part.stockquantitychanged` events for parts you don't track	This event broadcasts to every subscribed organization, not just yours	Filter on `keys.Part` client-side if you only care about specific parts.

Authentication — the bearer token and client-app-name header needed to call any dataUrl.
Orders, Quotes, Catalog — the APIs each event's dataUrl points back into.

On this page