# Overview

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:

```json
{
  "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](https://docs.partssource.com/documentation/event-catalog#event-envelope). For payload schemas per event type, see [Payload Objects](https://docs.partssource.com/documentation/webhooks/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](https://docs.partssource.com/documentation/webhooks/webhooks) for code examples in Node.js, C#, and Python.

{% hint style="warning" %}
**Replay protection:** Reject requests where `X-PS-Timestamp` is more than 5 minutes from your server's current time.
{% endhint %}

### 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](https://docs.partssource.com/documentation/webhooks/event-catalog) for the complete list with example payloads, and [Payload Objects](https://docs.partssource.com/documentation/webhooks/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          |