BNSF API Center | Push Notifications (Webhooks)

Push Notifications (Webhooks)

Our Push APIs allow BNSF to send detailed data to your systems at any given time, which means your computer system gets up-to-date information instantaneously. If interested, please complete and submit the below registration form below (be sure to enter a valid URL for us to call in the Webhook field).

Steps to receive webhooks

You can start receiving event notifications in your app using the steps in this section:

  1. Review the available events you want to monitor and their event payloads that you will need to parse.
  2. Create an externally available webhook endpoint as an HTTPS endpoint (URL) on your webserver.
  3. Handle requests from BNSF by parsing each event object and returning a 200 response status code.
  4. To avoid data loss, you can use a queuing mechanism that will capture the event payloads we send. Then, you can process them one at a time.
  5. For each event you are interested in, select the event from Available Events and register your publicly accessible HTTPS URL in the Registration form below.

Step 1: Review the available events

Bad Order

A bad order webhook notification is sent when we find a defect with a car and send it for repair. The payload looks like this: 

{
    "carInitial": "ABCX",
    "carNumber": "9364",
    "waybillNumber": "338216",
    "operatingStation333": "FRIONA",
    "operatingStationStateCode": "TX",
    "origin333": "LAFAYETTE",
    "originStateCode": "IN",
    "destination333": "FRIONA",
    "destinationStateCode": "TX",
    "equipmentLoadEmptyStatusCode": "L",
    "badOrderEventTypeDescription": "Initial",
    "eventDescription": "Bad Order",
    "eventDatetime": "2022-04-12-11.19.10",
    "badOrderDescription": "WHEEL ASSEMBLY",
    "badOrderEstimatedImpactDescription": "2 - 4 Hours Actual Repair Time",
    "shipmentEstimatedAvailabilityDatetime": "2022-04-05-20.16.00",
    "eventLocation333": "FRIONA",
    "eventLocationStateCode": "TX",
    "nextEventDescription": "TBD",
    "nextEventEstimatedDatetime": "",
    "nextRepairEventEstimatedDatetime": "",
    "nextEventLocation333": "",
    "nextEventLocationStateCode": "",
    "nextTrainId": "",
    "nextEventTrackNumber": "",
    "trackNumber": "3809",
    "shipper633": "ABCMATS",
    "shipperFullName": "AMERICAN MATERIALS",
    "consignee633": "HOLLYHOLLLC",
    "consigneeFullName": "HOLLY HOLDINGS LLC",
    "accountOfParty633": "",
    "accountOfPartyFullName": "",
    "careOfParty633": "ABC",
    "careOfPartyFullName": "ABC",
    "releaseToParty633": "",
    "releaseToPartyFullName": "",
    "beneficialOwner633": "",
    "beneficialOwnerFullName": "",
    "notifyParty633": "",
    "notifyPartyFullName": "",
    "payerOfFreight633": "",
    "payerOfFreightFullName": ""
}

Drayage Booking

A drayage booking notification webhook notification is sent when drayage has been booked to move an intermodal unit. The payload looks like this: 

{
    "drayageBookingNumber": "SH9997454",
    "destinationStateCode": "WA",
    "destinationStation333": "KENT",
    "destinationStationLotLocationName": "",
    "originStateCode": "WA",
    "originStation333": "SSEATTLE",
    "originStationLotLocationName": "",
    "drayageMovementMethodName": "Shuttle",
    "drayageShuttleTypeName": "UnitSpecific",
    "drayageShuttleMovementTypeName": "Yard",
    "truckingScac": "ABCD",
    "units": [
        {
            "equipmentInitial": "ABCU",
            "equipmentNumber": "81238"
        },
        {
            "equipmentInitial": "ABCU",
            "equipmentNumber": "101013"
        },
    ]
}

Geofence

A geofence webhook notification is sent when your passes through your pre-defined geofence. The payload looks like this: 

{
    "geofenceNotification": {
        "customerId": 135476,
        "sfdcId": "a681M0000008jKDQAY",
        "geofenceName": "George Killham",
        "geofenceExpirationDate": "2025-12-30",
        "geofenceCustomerMessage": "Shuttle Passing Stanford",
        "eventDate": "04-12-2022",
        "eventTime": "10:02",
        "trainId": "HGRFLAU112A",
        "customer633": "CHS",
        "equipmentCount": 2,
        "equipmentList": [
            {
                "equipmentId": "SDPX96295"
            },
            {
                "equipmentId": "TILX636213"
            }
        ],
        "loadEmpty": "EMPTY",
        "commodity": "ALL",
        "origin333": "ALL",
        "destination333": "ALL"
    }
}

Overload

An overload webhook notification is sent when we detect a car is overloaded. The payload looks like this: 

{
  "carInitial": "BNSF",
  "carNumber": "316324",
  "carOverloadedStatusCode": "OV",
  "carOverloadStatusTypeName": "Scaled",
  "equipmentGrossScaleWeightPounds": 279100,
  "origin333": "ARCAVAN",
  "originStateCode": "WI",
  "scale333": "KANCITY",
  "scaleStateCode": "KS",
  "shipmentLoadLimitPounds": 207300,
  "shipmentNetScaleWeightPounds": 223400,
  "shipmentScaleWeightRequiredReductionLb": 16100,
  "shippedByCustomer633": "",
  "shippedByCustomerCity333": "",
  "shippedByCustomerName": "",
  "shippedByCustomerStateCode": "",
  "shipperCity333": "DELAVAN",
  "shipper633": "XYZMAT",
  "shipperName": "XYZ MATERIALS",
  "shipperStateCode": "WI",
  "waybillDate": "2022-03-30",
  "waybillNumber": "308010",
  "totalLadingWeightPounds": 223400,
  "trackNumber": 2060
}

Local Service Notification

An LSN webhook notification is sent when are planning to serve your yard on a given day. The payload looks like this: 

{
    "service_indicator": "Y",
    "service_date": "April 12, 2022",
    "customer_633": "POOLECHEMICA",
    "station_333": "DALHART",
    "station_name": "DALHART",
    "station_state": "TX",
    "pick_up_car_count": 7,
    "pick_up_car_list": {
        "loaded_cars": "",
        "empty_cars": "BN468045,BN472398,GATX204679,GATX208108,ITFX91288,UTLX302755,UTLX302787,"
    },
    "deliver_car_count": 4,
    "deliver_car_list": {
        "loaded_cars": "BN467803,BNSF429817,BNSF432512,CAIX490052,",
        "empty_cars": ""
    },
    "train_id": "R-KAN0338-12I"
}

Price Update

A price update webhook notification is sent when a price changes that you are subscribed to. The payload looks like this: 

{
    "priceAuthorityUpdateDate": "Tue Apr 12 00:00:00 UTC 2022",
    "priceAuthorityList": {
        "priceAuthoiryNumber": "5162874856",
        "note": "Authority re-issued due to Origin Group changes.
Update group to exclude SJVR.",
        "priceDocumentURL": "https://ratedownload.rapid.bnsf.com/Rate/rateDownloadWebService?PA_Number=0000090020&PA_Name=BNSF&PA_Item_Number=0000001000&PA_Version_Number=0000000103"
    },
}

Step 2: Create an externally available webhook endpoint.

You will need to utilize the assistance of a qualified web developer to create program that can be exposed to the Internet via an HTTPS URL.

Step 3: Handle requests from BNSF

The URL should accept POST messages from api.bnsf.com. You should take care to validate the BNSF certificate when the request is received in order to minimize security risks on your side.

Step 4: Queuing Mechanism to Avoid Data Loss

As a best practice, you should capture the requests as they come in and then write them to a database with a status of unprocessed. Then, as you process the request records, you can mark them as processed. Following this approach will minimize data loss should your internal application become unavailable for a time.

Step 5: Push Registration: Register Events and Endpoints

For each event you want to receive, complete the Registration form found below. You can provide a single or multiple Webhook URL.

 

Push Registration

 


 

API Support

Monday – Friday, 8 am – 5 pm (Central Time)
For additional help, visit our API Support page.