# SiteTrax → Premiere Warehousing Webhook Integration

---

## 1. Quick reference


| Item               | Value                                                                                                   |
| ------------------ | ------------------------------------------------------------------------------------------------------- |
| **URL**            | `https://<BASE_URL>/api/webhooks/sitetrax` *(we will provide &lt;BASE_URL&gt;)*                         |
| **Method**         | `POST` only                                                                                             |
| **Content-Type**   | `application/json`                                                                                      |
| **Authentication** | Header `X-SiteTrax-Secret: <secret>` or `Authorization: Bearer <secret>` *(we will provide the secret)* |
| **Body**           | Non-empty JSON (single object or array of objects)                                                      |


---

## 2. Webhook URL

Use the exact URL for your environment:


| Environment    | URL                                                                    |
| -------------- | ---------------------------------------------------------------------- |
| **Staging**    | `https://dev.api.premierwarehousingservices.com/api/webhooks/sitetrax` |
| **Production** | `https://api.premierwarehousingservices.com/api/webhooks/sitetrax`     |


**Rules:**

- Use **HTTPS** in production.
- Call the URL with **POST** only; other methods are not accepted.

---

## 3. Authentication

We use a **shared webhook secret** to verify that requests come from you. We will send you one secret per environment (e.g. dev, test, live).

You must send this secret on **every request**, in one of these two ways:

### Option A: Custom header (recommended)


| Header name         | Value                  |
| ------------------- | ---------------------- |
| `X-SiteTrax-Secret` | The secret we gave you |


Example:

```
X-SiteTrax-Secret: TEST_a7gtddf18U3-ckjf7kFaf94agmcpYjHwl-aCTSTHOz2AU4gD2E8frhY-1UGjXkR
```

### Option B: Bearer token


| Header name     | Value             |
| --------------- | ----------------- |
| `Authorization` | `Bearer <secret>` |


Example:

```
Authorization: Bearer TEST_a7gtddf18U3-ckjf7kFaf94agmcpYjHwl-aCTSTHOz2AU4gD2E8frhY-1UGjXkR
```

**Important:**

- If you omit the secret or send the wrong value, we return **403 Forbidden**.
- Keep the secret confidential (e.g. do not log it or put it in client-side code).

---

## 4. Request format


| Requirement      | Details                                                          |
| ---------------- | ---------------------------------------------------------------- |
| **Content-Type** | Must be `application/json`                                       |
| **Body**         | Valid, non-empty JSON. Either one object or an array of objects. |


You can use your own field names and structure.

## 5. Example request

Full HTTP example:

```http
POST /api/webhooks/sitetrax HTTP/1.1
Host: api.premierewarehousing.com
Content-Type: application/json
X-SiteTrax-Secret: <your-secret>

{
  "video_name": "video24-05-07_09-43-03-39_01424",
  "type": "International Intermodal Vertical ID",
  "text": "TRBU5341840",
  "datetime": "2024-05-07T13:43:43.701000Z",
  "gps_lat": 30.4178413846,
  "gps_lon": -81.5642421112,
  "container_company": "CJ DARCL LOGISTICS LIMITED",
  "container_country": "India",
  "status": "Success",
  "status_code": "A0",
  "asset_image": "https://d11isnr6z7061v.cloudfront.net/...",
  "asset_heading": "R2L",
  "camera": "B8A44F9E3A9E",
  "feedback": "https://service.sitetrax.io/feedback/..."
}
```

**Testing in Postman:**

1. Method: **POST**
2. URL: Use Staging or Production URL based environment.
3. Headers:
  - `Content-Type` → `application/json`
    - `X-SiteTrax-Secret` → `<your-secret>`
4. Body → **raw** → **JSON** → paste your payload
5. Click **Send**

---

## 6. Responses

### Success (200 OK)

We have accepted and stored the payload.

Example response:

```json
{
    "status": "success",
    "message": "Webhook payload received."
}
```

### Error responses


| HTTP status                   | Meaning                             | What to do                                                                          |
| ----------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------- |
| **403 Forbidden**             | Invalid or missing webhook secret   | Send the correct secret in `X-SiteTrax-Secret` or `Authorization: Bearer <secret>`. |
| **422 Unprocessable**         | Validation failed (e.g. empty body) | Send a non-empty JSON body.                                                         |
| **500 Internal Server Error** | Our server error                    | Retry with backoff. If it continues, contact us.                                    |


Error body example:

```json
{
    "status": "forbidden",
    "message": "Invalid or missing webhook secret"
}
```

---

## 7. Checklist

Before going live, confirm:

- You have the correct **webhook URL** for your environment (dev/test/live).
- You have the correct **webhook secret** for that environment.
- Every request uses **POST** and **Content-Type: application/json**.
- The secret is sent on every request via **X-SiteTrax-Secret** or **Authorization: Bearer &lt;secret&gt;**.
- The request **body** is non-empty, valid JSON (object or array).
- Your client handles **200**, **403**, **422**, and **500** and retries only where appropriate (e.g. 500).

For the exact **base URL** and **secret** for each environment, contact the Premiere Warehousing team.