Skip to main content
Shiipp dispatches outbound webhooks to your configured endpoints whenever key events occur in the warehouse — giving your system real-time visibility into package and manifest activity without polling. The Payload Builder lets you take full control of the JSON structure those webhooks carry, so your receiving endpoint gets exactly the fields it expects without any transformation on your side.

​
Webhook Events

Shiipp fires webhooks for two event types:
EventTrigger
new_packageA new package is logged for your courier in the warehouse
status_updateA manifest associated with your courier changes status
Configure the destination URL for each event type in Courier Settings — api_url_add_package for package events and api_url_status_update for manifest status events.

​
Using the Payload Builder

The Payload Builder is only available to users with the Admin or Manager role. As a courier partner, configure your endpoint URLs in Courier Settings and coordinate with your Shiipp administrator to customise payload shapes if needed.
1

Open the Payload Builder

In the Shiipp dashboard, navigate to System > Webhook Payload Designer.
2

Select the payload type

Choose either new_package or status_update from the event type selector. The variable panel on the left updates to show variables available for that event.
3

Add fields

Drag fields from the variable panel onto the builder canvas. For each field, set:
  • Key — the JSON property name your system receives (e.g. tracking_no)
  • Value — a Shiipp variable that resolves at dispatch time (e.g. {{tracking_number}})
4

Set the root type

Choose whether your payload root is a JSON object {} or an array [] to match your receiving endpoint’s expected structure.
5

Preview and save

Click Preview to see a sample of the generated JSON with example values substituted in. When you are satisfied with the structure, click Save.

​
Available Variables

Use these variables when building the payload for the new_package event.
VariableDescription
{{package_id}}Internal package UUID
{{tracking_number}}Carrier tracking number
{{house_number}}Internal warehouse reference number
{{weight}}Package weight in LBS
{{user_code}}Customer code
{{first_name}}Customer first name
{{last_name}}Customer last name
{{shipper}}Shipper or vendor name
{{description}}Package contents description
{{entry_date_time}}Date and time the package was logged

​
Example Payload

Here is an example of a new_package payload shaped in the Payload Builder and the resolved JSON your endpoint receives when a package is logged: 
{
  "trackingNo": "{{tracking_number}}",
  "warehouseRef": "{{house_number}}",
  "customer": {
    "code": "{{user_code}}",
    "name": "{{first_name}} {{last_name}}"
  },
  "weight": "{{weight}}",
  "shipper": "{{shipper}}",
  "loggedAt": "{{entry_date_time}}"
}

​
Webhook Delivery

Shiipp sends all webhooks as POST requests with the following headers:
HeaderValue
Content-Typeapplication/json
AuthorizationBearer <your_api_token>
Your api_token is configured in Courier Settings and is the same token Shiipp uses for the customer sync request. Validate this token on your receiving endpoint to confirm the request originates from Shiipp.
If your endpoint does not return an HTTP 2xx response, Shiipp retries the delivery up to 5 times using exponential backoff. The retry intervals are approximately 30 seconds, 2 minutes, 10 minutes, 30 minutes, and 2 hours. If all five retries fail, the event is marked as undelivered and no further attempts are made.
Open the System Logs in the Shiipp dashboard to view recent webhook delivery attempts. Each entry shows the target URL, the HTTP response code received, and the timestamp of the attempt. Use this to diagnose delivery failures and verify that your endpoint is receiving payloads correctly.
Make sure your webhook endpoint responds within a reasonable timeout (recommended: under 5 seconds). Long-running processes triggered by a webhook should be handled asynchronously — acknowledge the request immediately and process the payload in the background to avoid missed retries.