> ## Documentation Index
> Fetch the complete documentation index at: https://developers.perform.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Shipment update (format 5.0)

> Sent to your configured endpoint whenever a Shipment has new events.
One webhook per update cycle, even when several triggers fire — the
`trigger` array lists every trigger the cycle satisfied.

**Delivery:** HTTPS POST, JSON body. Respond with HTTP 200. Without a
200, Perform.AI retries up to **3 times, 5 minutes apart**, then stops.

**Authentication:** each request carries an `HTTP-X-Hmac-SHA256` header
— the HMAC-SHA256 of the raw request body, keyed with the
Authentication Key from **Integrations > Webhooks**. Recompute and
compare to verify the sender.

Your account is configured for exactly one payload format version —
confirm which with your account team.



## OpenAPI

````yaml specs/public-api-v5.yaml webhook shipment-update-v5-0
openapi: 3.1.0
info:
  title: Perform.AI Public API (v5)
  version: 5.0.0
  description: |-
    The Perform.AI Public API lets you create and manage shipments, returns,
    bookings, tracking events, and documents, and retrieve reference data such
    as PUDO locations and carrier configurations.

    All endpoints accept HTTPS connections only and are secured with OAuth 2.0.
    Generate a Bearer access token with your API credentials (Client ID and
    Client Secret, from **Integrations > API** in your account), then send it in
    the `Authorization` header of every request.

    This specification covers the following endpoints:
    - `POST /auth/oauth/token/`
    - `POST /v5/shipment/`
    - `POST /v5/shipment/update/`
    - `POST /v5-2-0/shipment/update/`
    - `GET /v5/shipment/list/`
    - `GET /v5/shipment/details/`
    - `GET /v5-2-0/shipment/details/`
    - `POST /v5/events/create/`
    - `POST /v5/return/`
    - `POST /v5/return/update/`
    - `GET /v5/shipments/documents/`
    - `GET /v5/shipments/documents/{document_uuid}/`
    - `GET /v5/shipments/documents/labels/`
    - `POST /v5/booking/`
    - `GET /v5/pudo-locations/`
    - `GET /v5/carrier-configs/`
servers:
  - url: https://api.perform.ai
security:
  - BearerAuth: []
tags:
  - name: Authentication
    description: Generate the Bearer access token used by every other endpoint.
  - name: Shipments
    description: Create, update, search, and retrieve Shipments.
  - name: Events
    description: Add manual tracking events to Shipments.
  - name: Returns
    description: Create and update Returns and their Return Shipments.
  - name: Documents
    description: Retrieve documents attached to Shipments.
  - name: Booking
    description: Book Open Shipments with carriers and provision shipping labels.
  - name: PUDO locations
    description: Search pick-up/drop-off locations across your configured carriers.
  - name: Carrier configurations
    description: Discover the carriers configured in your account.
  - name: Webhooks
    description: Shipment update payloads Perform.AI pushes to your endpoint.
paths: {}
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Used by every functional endpoint. Generate the token with `POST
        /auth/oauth/token/` and send it as `Authorization: Bearer {token}`.

````