WebHooks

Webhooks notify your applications when events occur in TMS.ai without requiring constant polling. When a subscribed event happens (like an order status change), TMS.ai sends an HTTP POST request to your configured URL with event details in JSON format.

This event-driven approach reduces API calls and provides real-time notifications. Instead of checking every few minutes for status changes, your system receives immediate notifications when events actually occur.

Currently supported events:

At present, the default event available is Order Status Changed, which triggers when the status of an order changes. The webhook functionality is currently limited in terms of supported events and custom event definitions.

Event payload structure:

When an event occurs, TMS.ai sends a POST request with this JSON structure:

{
  "id": "string",
  "type": "string",
  "refId": "string",
  "ownerId": "string",
  "orgId": "string",
  "json": {
    // Event-specific data
  },
  "createdAt": "string",
  "objectKey": "string"
}
```

All events share common attributes: id, type, refId, ownerId, orgId, createdAt, and objectKey.

**Setting it up:**

1. Build an HTTPS endpoint on your server that can receive POST requests
2. Implement logic to parse the JSON payload and execute your business logic
3. Ensure your endpoint responds with a 2xx HTTP status code to acknowledge receipt
4. Create the webhook in TMS.ai by making a POST request to the API:
```
POST https://network.roserocket.com/api/v2/platformModel/objects
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "objectKey": "webhookDestination",
  "json": {
    "name": "Test to XYZ Freight",
    "url": "https://hooks.XYZfreightcorporation.com/hooks/catch/15958505/3x03dpa/",
    "subscriptions": [
      {
        "objectKey": "webhookSubscription",
        "eventName": "Order Status Changed"
      }
    ]
  }
}

Important limitations:

• You can only specify a Webhook URL when registering subscriptions
• Basic Auth with ClientID and Client Secret is not yet available
• Currently limited to specific event types (primarily Order Status Changed)

Retry mechanism:

TMS.ai automatically retries failed webhook deliveries:

• Upon event occurrence, the payload is sent to all subscribed webhooks
• If your server responds with a failure code, TMS.ai retries up to 3 times
• 30-second delay between retry attempts
• Webhooks provide at-least-once delivery guarantees
• If all retries fail, delivery is not guaranteed

Viewing webhook history:

You can view webhook history for up to 7 days from the Webhooks section in API settings. This includes both successful and failed webhook deliveries, helping you troubleshoot integration issues.

Common issues and troubleshooting:

If webhooks aren't working, check:

• Incorrect URL: Verify the webhook endpoint URL is accurate
• Incorrect paths: Confirm the paths specified for your webhook are correct
• Server not responding: Ensure your server is accessible and responding with 2xx status codes
• Timeout issues: Your endpoint must respond within a reasonable timeframe

Refer to the Webhook Receipts section in API settings for detailed information on failed attempts.

Processing webhooks:

Your webhook endpoint should:

1. Receive the POST request from TMS.ai
2. Parse the JSON payload
3. Validate it's from TMS.ai (based on your registered webhook configuration)
4. Execute your business logic based on the event type
5. Return a 2xx HTTP status code immediately (within timeout period)

For example, when receiving an "Order Status Changed" event, your system might:

• Update your customer portal with the new status
• Send notification emails to relevant parties
• Trigger downstream workflows in your operations
• Update records in your own database

The webhook functionality enables real-time integration without constantly polling the API. When an order status changes in TMS.ai, your system knows immediately and can react accordingly.