YMS Webhook Integration Guide

1. Overview

YMS (Yard Management System) provides a Webhook notification service. When critical business events occur within the yard (such as vehicle check-in or check-out), the system automatically pushes notifications to your designated endpoint. Your WMS or business system can receive these event notifications in real time, enabling efficient inter-system collaboration.

2. Prerequisites

Before configuring, please confirm the following:

• You have administrator access to the YMS system
• You have prepared a publicly accessible HTTPS endpoint
• Your endpoint can handle HTTP POST requests and return a 2xx status code upon successful processing

3. Configuring Webhooks

3.1 Accessing the Configuration Page

Log in to the YMS admin console and navigate to Admin > Webhook Configuration in the left sidebar.

On this page, you can view all configured Webhooks, including the associated yard, endpoint URL, subscribed events, status, and other details.

3.2 Creating a Webhook

Click the Create Webhook button in the upper-right corner to open the creation page.

Fill in the configuration fields as described below:

3.3 Editing a Webhook

Click Edit on a list entry to open the edit page, where you can modify existing configurations. The edit page also provides a Status toggle to enable or disable the Webhook.

3.4 Supported Event Types

Note: TASK_SYNC differs from other events — it is a synchronous call. When YMS creates, updates, or cancels a task, it calls your endpoint in real time and waits for a response. Your system must return a result in the specified format; otherwise, the task operation will fail. See Section 4.5 for details.

4. Notification Format

4.1 Request Method

When an event occurs, YMS sends a JSON-formatted notification to your endpoint via HTTP POST.

Please ensure your endpoint responds within 5 seconds; a timeout will be treated as a delivery failure.

4.2 Request Headers

Each notification includes the following standard request headers:

If you configured Custom Headers in your Webhook settings, those custom headers will also be included.

4.3 Notification Payload — Check-In/Check-Out Events

Applies to GATE_CHECK_IN, WINDOW_CHECK_IN, and GATE_CHECK_OUT events:

{
  "entryId": "entry record identifier",
  "appointmentId": "appointment identifier",
  "vehicleId": "vehicle identifier",
  "checkinTime": "2024-01-15T08:30:00",
  "checkoutTime": "2024-01-15T10:00:00",
  "entryStatus": "CHECKED_IN",
  "inboundAction": "RECEIVE",
  "inboundReceiptIds": ["REC-001", "REC-002"],
  "inboundCustomerIds": ["CUST-001"],
  "inboundCustomerNames": ["Customer A"],
  "inboundTaskId": "inbound task identifier",
  "outboundAction": "LOAD",
  "outboundLoadIds": ["LOAD-001"],
  "outboundCustomerIds": ["CUST-002"],
  "outboundCustomerNames": ["Customer B"],
  "outboundTaskId": "outbound task identifier",
  "inYardAction": "MOVE",
  "carrierId": "carrier identifier",
  "carrierName": "carrier name",
  "driverId": "driver identifier",
  "driverName": "driver name",
  "driverPhone": "driver phone number",
  "driverLicense": "driver license number",
  "licensePlate": "license plate number",
  "equipmentNo": "trailer number",
  "equipmentType": "equipment type",
  "sealNo": "seal number",
  "receiptType": "REGULAR_RECEIPT",
  "dropOffLocationName": "drop-off location name",
  "dropOffLocationId": "drop-off location identifier",
  "pickUpLocationName": "pick-up location name",
  "pickUpLocationId": "pick-up location identifier"
}

Field Descriptions:

Tip: Some fields may be null depending on the actual business scenario. Please handle null values appropriately on your receiving end.

Enum Value Reference

entryStatus (Entry Status):

inboundAction (Inbound Action):

outboundAction (Outbound Action):

inYardAction (In-Yard Action):

equipmentType (Equipment Type):

4.4 Notification Payload — Task Sync Event (TASK_SYNC)

TASK_SYNC is a synchronous call event, fundamentally different from other asynchronous notification events:

When YMS needs to create, update, or cancel a task, it calls your endpoint in real time and determines whether the task operation succeeds based on your response.

Request Payload

{
  "taskId": "YMS task identifier",
  "entryId": "entry record identifier",
  "taskType": "RECEIVE",
  "receiptIds": ["receipt-001", "receipt-002"],
  "loadIds": ["load-001"],
  "operate": "CREATE",
  "dockId": "dock identifier",
  "dockName": "dock name",
  "equipmentNo": "trailer number",
  "equipmentType": "equipment type",
  "loadMode": "LIVE_LOAD",
  "receiptType": "REGULAR_RECEIPT",
  "assigneeUserId": "assignee user identifier"
}

Field Descriptions:

Some fields may be null depending on the specific task type and operation scenario.

Response Format Requirements

Your system must return a JSON response in the following format; otherwise, YMS will treat the call as failed:

Success Response:

{
  "code": 200,
  "success": true,
  "msg": null,
  "data": {
    "assigneeUserId": "assignee user identifier",
    "assigneeUserName": "assignee user name"
  }
}

Failure Response:

{
  "code": 400,
  "success": false,
  "msg": "reason for failure",
  "data": null
}

Response Field Descriptions:

Determination Rules:

• success is true → YMS considers the task operation successful
• success is false or the response body is empty → YMS considers the task operation failed, and the operation will be aborted

Request Headers

TASK_SYNC requests include the following standard request headers:

If you configured Custom Headers in your Webhook settings, those custom headers will also be included.

4.5 Notification Payload — Entry Reject Event

Applies to the ENTRY_REJECT event. The payload structure is the same as check-in/check-out events, with entryStatus fixed as REJECTED and an additional rejectReason field:

{
  "entryId": "entry record identifier",
  "appointmentId": "appointment identifier",
  "vehicleId": "vehicle identifier",
  "checkinTime": "2024-01-15T08:30:00",
  "checkoutTime": "2024-01-15T10:00:00",
  "entryStatus": "REJECTED",
  "rejectReason": "reason for rejection",
  "inboundAction": "RECEIVE",
  "inboundReceiptIds": ["REC-001", "REC-002"],
  "inboundCustomerIds": ["CUST-001"],
  "inboundCustomerNames": ["Customer A"],
  "inboundTaskId": "inbound task identifier",
  "outboundAction": "LOAD",
  "outboundLoadIds": ["LOAD-001"],
  "outboundCustomerIds": ["CUST-002"],
  "outboundCustomerNames": ["Customer B"],
  "outboundTaskId": "outbound task identifier",
  "inYardAction": "MOVE",
  "carrierId": "carrier identifier",
  "carrierName": "carrier name",
  "driverId": "driver identifier",
  "driverName": "driver name",
  "driverPhone": "driver phone number",
  "driverLicense": "driver license number",
  "licensePlate": "license plate number",
  "equipmentNo": "trailer number",
  "equipmentType": "equipment type",
  "sealNo": "seal number",
  "receiptType": "REGULAR_RECEIPT",
  "dropOffLocationName": "drop-off location name",
  "dropOffLocationId": "drop-off location identifier",
  "pickUpLocationName": "pick-up location name",
  "pickUpLocationId": "pick-up location identifier"
}

Field Descriptions:

5. Retry Mechanism

When your endpoint returns a non-2xx status code or the response times out, the system will automatically retry.

• The number of retries is determined by the Max Attempts value in your configuration
• The retry interval starts at Initial Delay Seconds and doubles with each attempt (exponential backoff)
• After exceeding the maximum retry count, the notification will be marked as delivery failed

Retry Interval Example:

Using Initial Delay Seconds = 10 seconds and Max Attempts = 8 as an example:

Each retry includes a ±10% random jitter to prevent multiple notifications from retrying simultaneously and causing congestion.

6. Viewing Delivery Records

On the Delivery Tasks page, you can view the delivery status of all notifications.

You can filter by yard, delivery status, and event type.

Delivery Status Descriptions

Viewing Delivery Details

Click Detail on a record to view the complete request and response information for troubleshooting.

7. Receiver Development Guidelines

7.1 Basic Requirements

7.2 Deduplication

Due to network issues or the retry mechanism, the same event may be delivered multiple times. It is recommended to use the X-YMS-Event-Id header for deduplication to ensure the same event is not processed more than once.

7.3 Sample Code

Java (Spring Boot)

@RestController
@RequestMapping("/webhook")
public class YmsWebhookReceiver {
 
    @PostMapping("/receive")
    public ResponseEntity<String> handleNotification(
            @RequestHeader("X-YMS-Event-Id") String eventId,
            @RequestHeader("X-Event-Type") String eventType,
            @RequestBody Map<String, Object> payload) {
 
        // Deduplication check
        if (isAlreadyProcessed(eventId)) {
            return ResponseEntity.ok("OK");
        }
 
        // Process business logic based on event type
        switch (eventType) {
            case "GATE_CHECK_IN":
                processGateCheckIn(payload);
                break;
            case "GATE_CHECK_OUT":
                processGateCheckOut(payload);
                break;
            case "WINDOW_CHECK_IN":
                processWindowCheckIn(payload);
                break;
            case "ENTRY_REJECT":
                processEntryReject(payload);
                break;
        }
 
        markAsProcessed(eventId);
        return ResponseEntity.ok("OK");
    }
}

Python (Flask)

from flask import Flask, request, jsonify
 
app = Flask(__name__)
 
@app.route('/webhook/receive', methods=['POST'])
def handle_notification():
    event_id = request.headers.get('X-YMS-Event-Id')
    event_type = request.headers.get('X-Event-Type')
    payload = request.get_json()
 
    # Deduplication check
    if is_already_processed(event_id):
        return jsonify({"message": "OK"}), 200
 
    # Process based on event type
    if event_type == 'GATE_CHECK_IN':
        process_gate_check_in(payload)
    elif event_type == 'GATE_CHECK_OUT':
        process_gate_check_out(payload)
    elif event_type == 'WINDOW_CHECK_IN':
        process_window_check_in(payload)
    elif event_type == 'ENTRY_REJECT':
        process_entry_reject(payload)
 
    mark_as_processed(event_id)
    return jsonify({"message": "OK"}), 200

7.4 Recommendations

• Respond quickly: It is recommended to return a success response immediately upon receiving the notification, then process the business logic asynchronously
• Log requests: Save the received headers and notification payload for future troubleshooting
• Authentication: Use Custom Headers to configure authentication credentials (e.g., a Token) and verify the request source on your receiving end

8. Data Isolation

• Each Webhook configuration is associated with a specific yard
• Event notifications are only pushed to Webhook configurations for the corresponding yard
• Disabled configurations will not receive any notifications
• Multiple Webhooks can be configured for the same yard, each operating independently

9. FAQ

Q: My endpoint is not receiving notifications?

Please check the following in order:

1. Is the Webhook configuration enabled?
2. Have you subscribed to the corresponding event type?
3. Is the endpoint publicly accessible?
4. Is the endpoint using HTTPS?
5. Check the Delivery Tasks page for specific delivery status and error messages

Q: How can I verify that a notification is from YMS?

It is recommended to set a secret authentication Token via Custom Headers when creating the Webhook, and validate that value on your receiving end.

Q: Can the same event be received multiple times?

Yes, duplicate notifications may occur when delivery failures trigger retries. Use X-YMS-Event-Id for deduplication.

Q: Can I configure multiple Webhooks for the same yard?

Yes. Each Webhook can subscribe to different event types. When an event occurs, all matching configurations will receive the notification.

Q: What are the requirements for the endpoint URL?

The endpoint must use HTTPS and be publicly accessible over the internet.

10. Technical Support

If you encounter any issues during integration, please contact the YMS technical support team for assistance.