> For the complete documentation index, see [llms.txt](https://constanza-gobbo.gitbook.io/technical-documentation-portfolio/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://constanza-gobbo.gitbook.io/technical-documentation-portfolio/parceltrack-api/parceltrack-api-webhooks-sample.md).

# ParcelTrack API Webhooks - Sample

*Sample API documentation for a fictional shipment tracking service (ParcelTrack), written from the perspective of a contracted technical writer. This project demonstrates my ability to document webhook systems, including delivery guarantees, retry behavior, signature verification, and event payload structure. The focus was on clarity, security, and real-world developer experience.*

### Quickstart: Receive your first webhook

Follow these steps to receive your first ParcelTrack webhook event.

{% stepper %}
{% step %}

### Create a webhook subscription

Register a webhook endpoint in your ParcelTrack dashboard or via the API.

Provide:

* A publicly accessible HTTPS URL
* The events you want to subscribe to (for example, `shipment.delivered`)

After creating the subscription, store the signing secret securely. It will be displayed only once.
{% endstep %}

{% step %}

### Create a webhook endpoint

Create an HTTPS endpoint that accepts `POST` requests.

Example (Node.js with Express):

```jsx
app.post('/webhooks/parceltrack', (req, res) => {
  console.log('Received event:', req.body);
  res.status(200).send('OK');
});
```

Your endpoint must return an HTTP `2xx` status code to acknowledge successful receipt.
{% endstep %}

{% step %}

### Trigger a test event

Create or update a shipment to trigger one of your subscribed webhook events.

ParcelTrack will send a `POST` request to your configured endpoint.

You should receive a payload similar to:

```json
{
  "id": "evt_7fd91",
  "type": "shipment.delivered",
  "created_at": "2026-03-15T16:04:11Z",
  "data": {
    "shipment": {
      "id": "shp_92kf3",
      "status": "delivered"
    }
  }
}
```

{% endstep %}

{% step %}

### Verify the webhook signature

Before processing the event in production, verify the `ParcelTrack-Signature` header using your signing secret. See Webhook Security for details.
{% endstep %}
{% endstepper %}

### Webhooks Overview

ParcelTrack uses webhooks to notify client applications when shipment-related events occur. When a subscribed event happens, ParcelTrack sends an HTTP `POST` request to the client’s configured webhook URL. For example, ParcelTrack can notify your server when a shipment enters transit or is out for delivery.

#### Receiving webhook events

You must provide an HTTPS endpoint that accepts `POST` requests. Webhook requests are sent from ParcelTrack to your server.

To acknowledge successful receipt of a webhook event, your endpoint must respond with an HTTP `2xx` status code. If ParcelTrack does not receive a successful response, it will retry delivery up to four times.

Your endpoint should be designed to handle duplicate deliveries and out-of-order events. See Delivery and Retry Behavior for details.

#### Verifying webhook authenticity

All webhook requests are signed using an HMAC SHA-256 signature. Your application is expected to verify webhook authenticity using a shared secret before processing the event.

### Supported events

ParcelTrack sends webhook events when the lifecycle state of a shipment changes. The following events are supported:

| **Event**                   | **Trigger**                        |
| --------------------------- | ---------------------------------- |
| `shipment.created`          | A new shipment is created          |
| `shipment.in_transit`       | Shipment enters transit            |
| `shipment.out_for_delivery` | Shipment is out for delivery       |
| `shipment.delivered`        | Shipment is delivered successfully |
| `shipment.delivery_failed`  | A delivery attempt fails           |

### Delivery and retry behavior

Webhook delivery is **at-least-once**. If ParcelTrack does not receive an HTTP `2xx` response from your endpoint, the webhook event will be retried.

Retry schedule:

* Immediately
* After 5 minutes
* After 30 minutes
* After 2 hours

After four unsuccessful delivery attempts, the event is marked as failed.

ParcelTrack does not guarantee event ordering. Events may be delivered more than once, and some intermediate events may be skipped.

Your webhook endpoint should be designed to handle duplicate deliveries, out-of-order events, and missing events safely.

### Payload structure

All webhook events share a common envelope structure. Each event includes the following top-level fields:

* `id`: The unique identifier of the webhook event.
* `type`: The event type (see Supported Events).
* `created_at`: ISO 8601 timestamp indicating when the event occurred.
* `data`: Object containing event-specific information. The structure of this object depends on the event type.

The `data` object contains details related to the specific event, such as shipment status, carrier, and tracking number.

#### Example payload

```json
{
  "id": "evt_7fd91",
  "type": "shipment.delivered",
  "created_at": "2026-03-15T16:04:11Z",
  "data": {
    "shipment": {
      "id": "shp_92kf3",
      "status": "delivered",
      "carrier": "ups",
      "tracking_number": "1Z999AA10123456784"
    }
  }
}
```

### Webhook security

All webhook requests are signed to allow verification of authenticity. ParcelTrack uses an HMAC SHA-256 signature.

The signing secret is generated when the webhook subscription is created and is displayed only once.

#### Event headers

```plaintext
ParcelTrack-Signature: t=1710509051,v1=5f2a3c9e...
ParcelTrack-Event: shipment.delivered
```

The `ParcelTrack-Signature` header includes the following values:

* `t`: Unix timestamp indicating when the event was sent
* `v1`: HMAC SHA-256 signature of the raw request body, generated using the shared secret

#### Verifying the webhook event

* Use the `t` timestamp to calculate the time elapsed since the event was sent. Reject requests with a timestamp older than 5 minutes to protect against replay attacks.
* Recompute the HMAC SHA-256 signature using the raw request body and your shared secret.
* Compare the computed signature to the `v1` value using a constant-time comparison.

Only process the webhook event if the signature verification succeeds.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://constanza-gobbo.gitbook.io/technical-documentation-portfolio/parceltrack-api/parceltrack-api-webhooks-sample.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.