Webhooks

Overview

Samtec's webhooks push a lightweight HTTP POST to your endpoint whenever one of five events happens: an order line's status changes, a shipment ships, a tracked opportunity updates, a part's stock quantity changes, or an invoice is created. 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.
`invoice.created`	`Invoice Created`	An invoice file is created. Sent to the first subscribed customer found among the invoice's line items.

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.

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.

TODO: confirm with webhook team

The field names above are shown in PascalCase to match the internal C# model. The outbound payload is built with a third-party serializer whose casing behavior for this specific call could not be independently confirmed from source alone. Confirm actual wire casing before treating this as authoritative.

`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

{
  "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-14",
    "ExpirationDate": "2026-11-14"
  }
}

`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"
  }
}

`invoice.created` — Invoice Created

Keys: InvoiceNumber, InvoiceDate

Only the first subscribed customer found among the invoice's line items receives this — if an invoice spans multiple customers, the others don't get a separate call for it.

{
  "CompanyName": "Samtec",
  "TraceIdentifier": "e0f4a7d3-88c1-4b52-9d4a-1a7f6c203be9",
  "EventName": "Invoice Created",
  "EventTime": "2026-08-14T20:01:33.556Z",
  "DataUrl": "https://api.samtec.com/invoice/v1?invoiceNumber=INV-2054187",
  "Keys": {
    "InvoiceNumber": "INV-2054187",
    "InvoiceDate": "2026-08-14"
  }
}

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.

[ TODO: confirm with webhook team ] — whether HTTPS is required for your endpoint, contractually or operationally. Nothing in the delivery path itself rejects a non-HTTPS URL.

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.

[ TODO: confirm with webhook team ] — the current process for submitting this configuration. Given this portal's existing manual, email-based token onboarding (see Onboarding), apionboarding@samtec.com is the most likely path, but this couldn't be confirmed directly.

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 your configured timeout. [ TODO: confirm with webhook team ] the deployed timeout value — the default in code is 100 seconds absent an environment-specific override, which isn't visible from outside Samtec's infrastructure.

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 some number of times before landing in a dead-letter queue with 14 days of retention. [ TODO: confirm with webhook team ] the exact retry count and interval — these are configured at deploy time and aren't visible from the application source.
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