Webhook Subscriptions

Webhook subscriptions enable event-driven integration by pushing structured event payloads to a configured HTTP endpoint when defined actions occur within Consignly. Instead of polling the API for changes, a system can receive real-time notifications as events are published.

Key concepts:

Subscription: A registration linking an event type to a target URL, with optional signing keys and partner scope filters.
Event type: The specific lifecycle action that triggers a delivery (e.g., consignment-status-updated).
Payload envelope: Every event is wrapped in a common JSON structure regardless of type.
Signing keys: Optional HMAC-SHA256 keys used to sign each payload so consumers can verify authenticity.
Partner scoping: Consignment and schedule subscriptions can be filtered to a specific client or carrier partner.

A webhook event payload has an at-least one delivery and will retry when the receiving endpoint does not respond with a 200 status code or in a timely manner.

Subscription Lifecycle

Create → (optional) Test → ... → Delete

A subscription is created with a target URL, event type, and optional signing keys and partner filters.
Use the test endpoint to trigger a webhook-test delivery and verify the destination endpoint is reachable and processing correctly.
Subscriptions remain active until explicitly deleted. There is no pause or disable state — delete and re-create to change configuration.

Payload Envelope

Every webhook delivery uses this outer structure:

{
  "eventType": "consignment-status-updated",
  "event": { ... },
  "timestamp": 638306981121668077
}

Field	Type	Description
`eventType`	string	Kebab-case event type identifier
`event`	object	Event-specific payload (see Event Types below)
`timestamp`	long	Ticks representing when the event was published

Signing and Payload Verification

Signing keys are optional but strongly recommended for production use. When a signing key is configured, Consignly signs the raw JSON body using HMAC-SHA256 and includes the hex-encoded signature in a custom request header.

Header	Description
`X-Consignly-Signature-1`	HMAC-SHA256 signature using `signingKey1`
`X-Consignly-Signature-2`	HMAC-SHA256 signature using `signingKey2` (if configured)
`X-Consignly-Operation-Id`	Correlation/idempotency identifier for the delivery attempt

Verification algorithm:

Retrieve the raw request body as a UTF-8 string.
Compute HMAC-SHA256(body, signingKey) using the stored key.
Hex-encode the result (lowercase).
Compare the computed value to the received X-Consignly-Signature-1 header — reject the request if they do not match.

Zero-downtime key rotation: Two signing keys are supported to allow rotation without dropped deliveries. Rotate by updating signingKey2 first, verifying it works, then promoting it to signingKey1.

Webhook Verification

For subscriptions registered via the API webhook endpoints, Consignly sends a verification request to the target URL before the subscription becomes active:

{
  "eventType": "webhook-verification",
  "timestamp": 638306981121668077,
  "correlationId": "...",
  "verificationId": "a7f2c1d4-..."
}

The endpoint must respond 200 OK with the echoed VerificationId:

{
  "VerificationId": "a7f2c1d4-..."
}

Portal-registered webhook subscriptions do not use this verification step.

Event Types

Consignment Events

Event Type	Trigger
`consignment-created`	A new consignment has been created
`consignment-general-updated`	The general details of a consignment were updated
`consignment-route-updated`	The route/carrier/container details were updated
`consignment-container-updated`	Container details were updated
`consignment-metrics-updated`	Consignment metrics were updated
`consignment-tasks-updated`	Tasks on the consignment were updated
`consignment-consumables-updated`	Consumables were updated
`consignment-products-updated`	Products on the consignment were updated
`consignment-pod-created`	A proof of delivery was added
`consignment-import-pending-reconciliation`	An imported consignment requires manual reconciliation
`consignment-import-reconciled`	An imported consignment was reconciled and created
`consignment-status-updated`	The consignment status changed
`consignment-service-type-updated`	The service type was updated
`consignment-tracking-updated`	Tracking information was updated
`consignment-connection-action-manual-trigger`	A connection action was manually triggered on a consignment

Consignment event scope: When creating a subscription, clientPartnerId and/or carrierPartnerId can be set to restrict deliveries to consignments matching those partners. Omit both to receive events for all consignments in the organisation.

Schedule Events

Event Type	Trigger
`partner-schedule-created`	A partner schedule was created
`partner-schedule-removed`	A partner schedule was removed
`partner-schedule-general-updated`	General schedule details were updated
`partner-schedule-status-updated`	The schedule status changed
`partner-schedule-transactions-updated`	Schedule transactions were updated
`partner-schedule-connection-action-manual-trigger`	A connection action was manually triggered on a schedule

Job Events

Event Type	Trigger
`job-created`	A new job was created
`job-updated`	A job was updated (including added/removed consignments)
`job-status-updated`	The job status changed
`job-connection-action-manual-trigger`	A connection action was manually triggered on a job

Job event scope: Job events are scoped to the organisation level. Partner ID filters do not apply to job events.

Event Payload Reference

Common fields (all events)

Field	Type	Description
`organisationId`	uuid	The organisation that owns the resource
`originConnectionId`	uuid	The connection that initiated the action

`consignment-created` / `consignment-import-reconciled`

Field	Type	Description
`consignmentId`	uuid	Consignment ID
`consignmentNumber`	string	Human-readable consignment number
`clientPartnerId`	uuid	Client partner
`carrierPartnerId`	uuid	Carrier partner
`type`	integer	Consignment type
`enteredDate`	datetime	Date entered
`originAddress`	object	`{ warehouseId, location }`
`destinationAddress`	object	`{ warehouseId, location }`

`consignment-status-updated`

Includes all consignment-created fields plus:

Field	Type	Description
`status`	integer	New consignment status
`previousStatus`	integer	Previous consignment status
`isVoid`	boolean	Whether the consignment is now void
`releasedPartnerProductIds`	uuid[]	Products released by this status change

`job-created`

Field	Type	Description
`jobId`	uuid	Job ID
`warehouseId`	uuid	Warehouse the job belongs to

`job-updated`

Includes job-created fields plus:

Field	Type	Description
`consignmentIds`	uuid[]	Consignments currently on the job
`wavePickData`	object	`{ style }` — wave pick style value

`job-status-updated`

Field	Type	Description
`jobId`	uuid	Job ID
`type`	integer	Job type
`status`	integer	New status
`previousStatus`	integer	Previous status
`consignmentIds`	uuid[]	Consignments on the job
`wavePickData`	object	`{ style }`

`partner-schedule-created` / `partner-schedule-general-updated`

Field	Type	Description
`partnerId`	uuid	Partner the schedule belongs to
`partnerScheduleId`	uuid	Schedule ID
`date`	date	Schedule date
`referenceNumber`	string	Reference number
`description`	string	Schedule description

`partner-schedule-status-updated`

Includes base schedule identifiers plus:

Field	Type	Description
`status`	integer	New schedule status

References

Help Centre: Event subscription payload definitions
Endpoint details: See endpoints/webhook-subscriptions.md

Jobs

Consignments