Overview

Real-time event notifications delivered to your endpoint

Webhooks deliver real-time HTTP POST notifications to your server when events occur in the PartsSource platform — orders created, shipments dispatched, line items backordered, and more. Instead of polling the API, your system receives events as they happen.

---

Getting Started

Webhook configuration is managed by the PartsSource implementation and integration team. To get started, you provide:

1. An HTTPS endpoint URL where PartsSource will deliver events (TLS required)

2. Which events you want — your integration team will help determine which event types are relevant

Contact your PartsSource integration representative to begin setup. Once configured, you'll receive a signing secret to verify that deliveries are authentic.

---

What You Receive

Each webhook delivery is an HTTP POST request to your endpoint containing a JSON envelope, delivery headers, and an HMAC-SHA256 signature.

Headers

Header	Description
X-PS-Signature	HMAC-SHA256 signature: sha256={hex_digest}
X-PS-Timestamp	Unix timestamp (seconds) when the request was signed
X-PS-Delivery-ID	Unique delivery attempt ID
X-PS-Delivery-Attempt	Attempt number (1–8)
X-Correlation-ID	Correlation ID for tracing

Body

The request body is a JSON envelope containing the event type, company context, and the event-specific payload:

{
  "event_type": "order.shipment.shipped",
  "company_id": 12345,
  "payload": {
    "line_item_id": 100,
    "tracking_number": "1Z999AA123456789",
    "carrier": "UPS",
    "shipped_at": "2024-01-18T15:30:00Z",
    "estimated_delivery_date": "2024-01-20"
  },
  "occurred_at": "2024-01-18T15:30:00Z",
  "correlation_id": "corr-abc123",
  "reference_id": 100,
  "source": "order-service"
}

For the full envelope schema, see the Event Catalog. For payload schemas per event type, see Payload Objects.

---

Signature Verification

Each delivery is signed so you can verify it came from PartsSource and wasn't tampered with.

1. PartsSource constructs a signed payload: {timestamp}.{request_body}

2. Computes HMAC-SHA256 using your webhook secret

3. Sends the result in the X-PS-Signature header as sha256={hex_digest}

To verify, reconstruct the signed payload on your end, compute the HMAC, and compare using a constant-time comparison. See the Implementation Guide for code examples in Node.js, C#, and Python.

Replay protection: Reject requests where X-PS-Timestamp is more than 5 minutes from your server's current time.

Secret Rotation

If your signing secret needs to be rotated, contact your PartsSource integration team. During the 24-hour grace period after rotation, deliveries include both X-PS-Signature (new secret) and X-PS-Signature-Previous (old secret). Accept either signature during this window.

---

Retry Behavior

When your endpoint returns a non-success response or times out, PartsSource retries with exponential backoff:

Attempt	Delay	Cumulative
1	Immediate	—
2	30 seconds	30s
3	2 minutes	2m 30s
4	10 minutes	12m 30s
5	30 minutes	42m 30s
6	2 hours	2h 42m
7	6 hours	8h 42m
8	12 hours	20h 42m

After 8 failed attempts, the delivery moves to a dead letter queue. Contact your integration team to replay failed deliveries.

Retryable: 408, 429, 500, 502, 503, 504

Not retried: 400, 401, 403, 404, 410

Circuit Breaker

If your endpoint fails 5+ times within 60 seconds, deliveries pause for 30 seconds. A single test delivery is then attempted — if it succeeds, normal delivery resumes.

---

Event Types

PartsSource publishes events across order lifecycle, approvals, shipments, and line item status changes. See the Event Catalog for the complete list with example payloads, and Payload Objects for full field schemas.

The specific events available to your integration will be determined during setup with your integration team.

---

Limits

Constraint	Value
Max payload size	1 MB
Response timeout	30 seconds
Timestamp tolerance	5 minutes
Secret rotation grace period	24 hours
Max retry attempts	8