Webhook Setup Guide
Send extracted document data to your other systems automatically
Overview
Webhooks send extracted data to your other systems, such as your CRM, ERP, accounting software or an application you have written yourself. Configure a webhook URL and StarShipper delivers the data as JSON. The payload is built from the whole shipment record, so a send carries the shipment and its documents together rather than one file on its own.
Per Document Type
Route a document type to its own endpoint, or take the whole shipment
Automatic Delivery
Sent once the shipment's documents have settled
Field Mapping
Rename fields to match your system's format
How it works: A webhook connection carries routes. A route is scoped either to the whole organisation, in which case it fires for any shipment, or to a particular document type, in which case it fires for shipments carrying a document of that type. Webhooks are the only destination with that per-document-type choice, so sending invoices to your accounts system and bills of lading to your TMS is one connection with two routes.
Basic Webhook Setup
Required fields for every webhook
| Field | Required | Description |
|---|---|---|
name | Required | A descriptive name to help you identify this webhook |
url | Required | The URL where data should be sent (must start with https://) |
method | Required | HTTP method: POST (most common), PUT, or PATCH |
auth_type | Optional | How to authenticate: none, basic, bearer, or api_key |
Tip: Give your webhook a clear name like "Send to Salesforce" or "ERP Invoice Import" so you can easily identify it later.
Authentication Options
Secure your webhook with authentication
Most systems require authentication to accept webhook data. Choose the method your receiving system supports:
No Authentication
Use for internal systems or endpoints that don't require auth. Not recommended for production.
Bearer Token
Sends an Authorization header with your token. Most common for APIs.
Authorization: Bearer your-token-hereBasic Auth
Uses username and password. Common for legacy systems.
Authorization: Basic base64(username:password)API Key
Sends your API key in a custom header. You specify the header name.
X-API-Key: your-api-key-hereField Mapping
Rename fields to match your system's expected format
Field mapping lets you rename the extracted fields before they're sent. This is useful when your receiving system expects specific field names.
Example: Rename fields for your CRM
If your CRM expects "vendor_name" but StarShipper extracts "shipper.name", you can map it:
shipper.name→vendor_nameinvoiceNumber→invoice_idtotalAmount→amount_dueWhere to configure: Field mapping is per integration and per document type. Go to Settings → Doc Types, pick the integration at the top of the page, and set the "Maps to" value on each field. The same field can go to two systems under two different names.
Payload Example
The shipment record posted to your endpoint
An example of the JSON body posted to your endpoint when a shipment is dispatched. Arrays are trimmed here; the full reference is on the Webhook Payload page.
{
"shipmentId": "3f9a2b18-5c47-4c1e-9a3d-7b6e0f2c8d41",
"stage": "shipment",
"organizationId": "b21c4e77-90aa-4f3b-8d52-1c6e9a04f7b3",
"referenceNumber": "SS-2026-004182",
"version": 3,
"hblNumber": "AION0025518",
"mblNumber": "MSCUZH492117",
"invoiceNumber": "INV-2026-001",
"invoiceDate": "2026-07-28",
"mode": "SEA",
"carrier": "MSC",
"originPort": "CNSHA",
"destinationPort": "AUBNE",
"eta": "2026-08-24",
"invoiceAmount": 15750,
"invoiceCurrency": "USD",
"containers": [
{
"containerNumber": "MSCU1234567",
"containerType": "40HC",
"weightUnit": "KG",
"lineItems": [
{
"lineNumber": 1,
"description": "Widget A",
"quantity": 100,
"unitPrice": 50,
"lineTotal": 5000
},
{
"lineNumber": 2,
"description": "Widget B",
"quantity": 150,
"unitPrice": 71.67,
"lineTotal": 10750
}
]
}
],
"parties": [
{
"role": "shipper",
"name": "Acme Corp",
"code": null,
"abn": null
},
{
"role": "consignee",
"name": "Global Imports Pty Ltd",
"code": null,
"abn": "51824753556"
}
],
"status": "in_transit",
"customsStatus": null,
"createdAt": "2026-08-03T04:12:08.410Z",
"updatedAt": "2026-08-12T22:47:31.902Z"
}Payload structure:
- document_id - Unique identifier for the document
- filename - Original file name
- document_type - AI-detected type (commercial_invoice, bill_of_lading, etc.)
- email_from/subject - Source email info (if received via email)
- data - All extracted fields (varies by document type)
For the complete payload structure including all fields, see the Webhook Payload Structure guide.