Skip to content

Webhook Endpoint Setup

This guide covers the technical requirements for implementing your webhook endpoint to receive real-time events from Tradecloud.

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

Your webhook must implement one of these authentication methods:

  • Standard: RFC 7617
  • Header: Authorization: Basic <base64(username:password)>
  • Use Case: Simple integrations with static credentials
  • 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)”

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 line
  • orderDocumentsEvent - Document attachments and updates

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 version and still differ.
  • If your system accepts webhooks and processes them later, and that processing can finish out of order, use version to recognise an older event: only a lower version is older. An equal one can still carry a change.
  • A retry delivers the same event again, with the same meta.messageId. Use meta.messageId to 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 version and 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 the meta.messageId.
  • version does not tell a new order from a changed one. Use eventName for that.

Implement the Shipment Webhook API to receive shipment notifications.

Event Characteristics:

  • Contains all shipment lines and documents
  • Filter changes using lastUpdatedAt timestamps
  • Process documents via download API when needed

When receiving document events:

  1. Extract Document ID - Get objectId from the event
  2. Download Content - Use appropriate download API:
  3. Process File - Handle the downloaded content in your system

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
  • 200 OK - Event processed successfully
  • 202 Accepted - Event queued for processing
  • 400 Bad Request - Invalid event data
  • 401 Unauthorized - Authentication failed
  • 500 Internal Server Error - Event processing error that a retry will not resolve, such as a functional error. Tradecloud does not retry it
  • 502 Bad Gateway - upstream ERP system temporary unavailability
  • 503 Service Unavailable - Temporary unavailability, or a transient processing error that a retry can resolve

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.

Once your webhook endpoint is implemented:

Configure webhook settings in the Tradecloud portal to enable event delivery.