Portal Configuration

Configure your webhook integrations in the Tradecloud portal to enable real-time event delivery to your systems.

Accessing Webhook Settings

1. Log in to the Tradecloud portal
2. Navigate to My Company (under your avatar menu)
3. Select the Settings tab
4. Locate the Webhook Integration section

Note

Admin Access Required: Only company administrators can configure webhook settings.

Order Events Configuration

Enable order webhook integration to receive notifications when orders are created, updated, or changed.

Event Selection

Configure which order events trigger webhook notifications:

Customization: Select events based on your integration capabilities and business process requirements. See complete event list for all available options.

Delivery Schedule Mode

Choose how order deliveries are structured in webhook payloads:

Mode	Payload Field	Use Case
Multiple Deliveries	orderEvent	Complex delivery schedules with multiple dates per line
Single Delivery	singleDeliveryOrderEvent	Simple orders with one delivery per order line

Learn More: Delivery Schedule vs Single Delivery documentation.

Order Lines

Choose which order lines a POST JSON webhook payload carries:

Option	Payload lines
Only changed order lines	The lines affected by the event
All order lines	Every line of the order

Only changed order lines is the default. With All order lines, lines holds every line of the order, including cancelled and completed lines, in buyer position order. Choose it when your system needs the complete order in every message.

This option is independent of the Delivery Schedule Mode: all four combinations are valid. It applies to the POST method with the JSON format only; a GET webhook and a tXML payload are not affected.

With All order lines, the payload is the order as it is when the webhook is sent, not as the event left it:

• It can show changes made by events you did not select in Event Selection. Selecting events decides when you receive a webhook, not what the order in it contains.
• The order line reason is absent. The order-level reason of the event is still present.
• eventName still tells which event triggered the webhook. Use it, not lastUpdatedAt or version, to decide whether an order is new or changed: OrderIssuedByBuyer and OrderResentBySupplier are new orders, every other event is a change.
• Compare the per-line lastUpdatedAt to find the lines that changed.

See Order version for what version means and how to recognise a retried event.

Document Events Configuration

Enable document webhook integration to receive notifications when order documents are attached or updated.

Event Sources:

• Buyer Documents - Documents added by order buyers
• Supplier Documents - Documents added by order suppliers
• Both - All document events regardless of source

See document events reference for complete event details.

Shipment Events Configuration

Enable shipment webhook integration to receive notifications about despatch advice and delivery updates.

Customize event selection based on your logistics processes. See shipment events reference for all available events.

Endpoint Configuration

Configure your webhook endpoint URL and HTTP method:

Requirements

• Method: POST (only supported HTTP method)
• URL: Must start with https:// (HTTP not supported)
• Accessibility: Endpoint must be publicly accessible from internet

Example: https://api.yourcompany.com/webhooks/tradecloud

Authentication Setup

Configure secure authentication for webhook requests. Choose from three supported methods:

Basic Authentication

Configuration:

• Standard: RFC 7617 compliant
• Username: Webhook service username
• Password: Webhook service password
• Header: Authorization: Basic <base64(username:password)>

Bearer Token

Configuration:

• Standard: RFC 6750 compliant
• Token: Static authentication token
• Header: Authorization: Bearer <token>

OAuth 2.0 (Microsoft Identity Platform)

Order webhook OAuth authentication uses the Microsoft Identity Platform via MSAL4J. It is not a general-purpose OAuth 2.0 client — custom OAuth extensions required by other security token services are not supported. Use Basic Authentication or a Bearer Token if your webhook endpoint is protected by a non-Microsoft identity provider.

Configuration Fields:

• Authentication URL: Microsoft token endpoint (authority URL)
  Example: https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token
• Client ID: Application (client) ID from your Microsoft Entra app registration
• Client Secret: Client secret from your Microsoft Entra app registration
• Scope: Granted scope for webhook access Example: https://your-webhook-endpoint/.default

Supported authority types (determined from the authentication URL path):

Authority	URL pattern	Example
Microsoft Entra ID (Azure AD)	Default	https://login.microsoftonline.com/{tenant}
ADFS	Path contains adfs	https://adfs.contoso.com/adfs
Azure AD B2C	Path contains tfp	https://{tenant}.b2clogin.com/{tenant}.onmicrosoft.com/{policy}

Grant type: OAuth 2.0 Client Credentials (RFC 6749 Section 4.4).

Caution

OAuth for order webhooks is available for order events and order document events only. Shipment webhooks do not support OAuth — use Basic Auth or Bearer Token instead.

Testing Configuration

Development Testing

Use webhook.site for initial configuration testing:

1. Generate test URL at webhook.site
2. Configure test webhook with the generated URL
3. Use placeholder credentials (webhook.site doesn’t validate auth)
4. Trigger test events to validate payload delivery
5. Inspect payloads in webhook.site interface

Integration Testing

1. Configure test endpoint in Tradecloud acceptance environment portal
2. Trigger test events through sample transactions
3. Validate event processing and response handling
4. Test error scenarios with various HTTP status codes

Production Validation

1. Configure production endpoint in Tradecloud production environment portal
2. Perform test transactions to trigger events
3. Validate event processing in your system
4. Monitor webhook logs for delivery confirmation