Webhook Endpoint Setup
This guide covers the technical requirements for implementing your webhook endpoint to receive real-time events from Tradecloud.
Technical Requirements
Section titled “Technical Requirements”Infrastructure Requirements
Section titled “Infrastructure Requirements”Your webhook endpoint must meet these mandatory requirements:
| Requirement | Details |
|---|---|
| Protocol | HTTPS only (HTTP not supported) |
| TLS Version | TLS 1.2 or 1.3 minimum |
| SSL Certificate | Valid certificate from recognized CA (no self-signed) |
| HTTP Method | POST method support |
| Content Types | JSON and/or tXML parsing capability |
| Internet Access | Publicly accessible from Tradecloud servers |
Authentication Support
Section titled “Authentication Support”Your webhook must implement one of these authentication methods:
Basic Authentication
Section titled “Basic Authentication”- Standard: RFC 7617
- Header:
Authorization: Basic <base64(username:password)> - Use Case: Simple integrations with static credentials
Bearer Token
Section titled “Bearer Token”- Standard: RFC 6750
- Header:
Authorization: Bearer <token> - Use Case: API key-based authentication
OAuth 2.0 (Microsoft Identity Platform, order webhooks only)
Section titled “OAuth 2.0 (Microsoft Identity Platform, order webhooks only)”- Scope: Microsoft Identity Platform only (Microsoft Entra ID, ADFS, Azure AD B2C) via MSAL4J – not a general-purpose OAuth 2.0 client
- Grant Type:
client_credentials(RFC 6749 Section 4.4) - Use Case: Webhook endpoints protected by Microsoft Entra ID (e.g. Azure API Management)
- Configuration: See Portal Configuration – OAuth
Webhook Implementation
Section titled “Webhook Implementation”Order Events
Section titled “Order Events”Implement the Order Webhook API to receive order-related events.
Event Types Available:
orderEvent- Multi-delivery order lines (delivery schedule mode)singleDeliveryOrderEvent- Single delivery per order lineorderDocumentsEvent- Document attachments and updates
Order version
Section titled “Order version”Every JSON order event carries version, the Tradecloud order version after
the event. Tradecloud delivers the events of an order one at a time, in the
order they happened:
- Some changes, such as line updates, do not raise the version, so two events
can carry the same
versionand still differ. - If your system accepts webhooks and processes them later, and that
processing can finish out of order, use
versionto recognise an older event: only a lowerversionis older. An equal one can still carry a change. - A retry delivers the same event again, with the same
meta.messageId. Usemeta.messageIdto avoid repeating the side effects of an event you already processed. - With All order lines, a retry reads the order again, so it can carry a
higher
versionand more recent lines, including changes from events you did not select, which send no webhook of their own. The payload is the complete order, so apply its lines even when you recognise themeta.messageId. versiondoes not tell a new order from a changed one. UseeventNamefor that.
Shipment Events
Section titled “Shipment Events”Implement the Shipment Webhook API to receive shipment notifications.
Event Characteristics:
- Contains all shipment lines and documents
- Filter changes using
lastUpdatedAttimestamps - Process documents via download API when needed
Document Processing
Section titled “Document Processing”When receiving document events:
- Extract Document ID - Get
objectIdfrom the event - Download Content - Use appropriate download API:
- Process File - Handle the downloaded content in your system
Response Handling
Section titled “Response Handling”Your webhook must return appropriate HTTP status codes:
Return 500 only when a retry cannot succeed: Tradecloud does not retry it and the event is not delivered again. For a failure that a later attempt can resolve, return 502 or 503.
| Status Code | Meaning | Tradecloud Action |
|---|---|---|
| 2xx | Success | Event marked as delivered |
| 4xx | Client Error | No retry |
| 500 | Server Error | No retry |
| >500 | Server Error | Retry with exponential backoff |
Recommended Response Codes
Section titled “Recommended Response Codes”200 OK- Event processed successfully202 Accepted- Event queued for processing400 Bad Request- Invalid event data401 Unauthorized- Authentication failed500 Internal Server Error- Event processing error that a retry will not resolve, such as a functional error. Tradecloud does not retry it502 Bad Gateway- upstream ERP system temporary unavailability503 Service Unavailable- Temporary unavailability, or a transient processing error that a retry can resolve
Testing Your Webhook
Section titled “Testing Your Webhook”Development Testing
Section titled “Development Testing”Use webhook.site for initial testing and payload inspection. It is a public third-party service: use it only from the acceptance environment with test orders, never with production data.
Next Steps
Section titled “Next Steps”Once your webhook endpoint is implemented:
Configure webhook settings in the Tradecloud portal to enable event delivery.
