Webhooks

Use webhooks to be notified about events that happen within the Traxo platform.

What is a Webhook? "The concept of a WebHook is simple. A WebHook is an HTTP callback: an HTTP POST that occurs when something happens; a simple event-notification via HTTP POST."

The Event Object

All events follow a similar convention of a "resource" and the "event" action separated by a dot as in "trip.created" or "email.updated". This convention allows a logical grouping of actions related to a particular resource.

{
    "id": "333333333333333333",
    "type": "trip.created",
    "created": "2017-11-01T01:00:00+00:00",
    "data": {
        "object": {
            "id": "761425449336840723",
            "first_name": "Chris",
            "last_name": "Stevens",
            "member_id": "812",
            "headline": "",
            "destination": "Arlington",
            "begin_datetime": "2017-10-06T11:00:00",
            "end_datetime": "2017-10-10T16:00:00",
            ....
        }
    }
}

id is the unique identifer for this event.

type is the event type in {resource}.{event} format.

created is the ISO8601 timestamp for the event.

data is the payload of the event with contents that vary by type.

In general, the event payload will contain an object representing the resource identified by the event type. The resource contents are the same as what the Traxo API would return for that resource.

Supported Events

Click or tap on each event to see additional details about the event.

Trip Events

Trip events are the most common and frequently used class of events. These events describe changes to trips and the segments that belong to them within a member's account.

Example:
{
    "id": "333333333333333333",
    "type": "trip.created",
    "created": "2017-11-01T01:00:00+00:00",
    "data": {
        "object": {
            "id": "211111111111111111",
            "member_id": "111111111111111111",
            "status": "Active",
            "destination": "Dallas",
            "admin_code": "TX",
            "country": "US",
            "lat": 32.7830543518066,
            "lon": -96.8066635131836,
            "begin_datetime": "2010-08-13T23:40:00.000Z",
            "end_datetime": "2010-08-14T23:40:00.000Z",
            "duration": "1",
            "distance": "380",
            "personal": 1,
            "business": 1,
            "privacy": "Buddies Only",
            "verified": "Y",
            "headline": "Test trip in Dallas",
            "first_name": "Don",
            "last_name": "Draper",
            "begin_time_zone_id": "America/Chicago",
            "end_time_zone_id": "America/Chicago",
            "begin_time_zone": "CDT",
            "end_time_zone": "CDT",
            "images": [
                {
                  "prefix": "https://www.traxo.com/images/flags/subdivisions/",
                  "suffix": "/us-ny.png"
                }
            ],
            "url": "https://www.traxo.com/trips/211111111111111111",
            "harvested": true,
            "created": "2008-11-08T09:37:07+0000",
            "updated": "2011-10-26T19:45:51+0000"
        }
    }
}
Example:
{
    "id": "333333333333333333",
    "type": "trip.updated",
    "created": "2017-11-01T01:00:00+00:00",
    "data": {
        "object": {
            "id": "211111111111111111",
            "member_id": "111111111111111111",
            "status": "Active",
            "destination": "Dallas",
            "admin_code": "TX",
            "country": "US",
            "lat": 32.7830543518066,
            "lon": -96.8066635131836,
            "begin_datetime": "2010-08-13T23:40:00.000Z",
            "end_datetime": "2010-08-14T23:40:00.000Z",
            "duration": "1",
            "distance": "380",
            "personal": 1,
            "business": 1,
            "privacy": "Buddies Only",
            "verified": "Y",
            "headline": "Test trip in Dallas",
            "first_name": "Don",
            "last_name": "Draper",
            "begin_time_zone_id": "America/Chicago",
            "end_time_zone_id": "America/Chicago",
            "begin_time_zone": "CDT",
            "end_time_zone": "CDT",
            "images": [
                {
                  "prefix": "https://www.traxo.com/images/flags/subdivisions/",
                  "suffix": "/us-ny.png"
                }
            ],
            "url": "https://www.traxo.com/trips/211111111111111111",
            "harvested": true,
            "created": "2008-11-08T09:37:07+0000",
            "updated": "2011-10-26T19:45:51+0000"
        }
    }
}
Example:
{
    "id": "333333333333333333",
    "type": "trip_segment.created",
    "created": "2017-11-01T01:00:00+00:00",
    "data": {
        "object": {
            "trip": {
                "id": "211111111111111111",
                "member_id": "111111111111111111",
                "status": "Active",
                "destination": "Dallas",
                "admin_code": "TX",
                "country": "US",
                "lat": 32.7830543518066,
                "lon": -96.8066635131836,
                "begin_datetime": "2010-08-13T23:40:00.000Z",
                "end_datetime": "2010-08-14T23:40:00.000Z",
                "duration": "1",
                "distance": "380",
                "personal": 1,
                "business": 1,
                "privacy": "Buddies Only",
                "verified": "Y",
                "headline": "Test trip in Dallas",
                "first_name": "Don",
                "last_name": "Draper",
                "begin_time_zone_id": "America/Chicago",
                "end_time_zone_id": "America/Chicago",
                "begin_time_zone": "CDT",
                "end_time_zone": "CDT",
                "images": [
                    {
                      "prefix": "https://www.traxo.com/images/flags/subdivisions/",
                      "suffix": "/us-ny.png"
                    }
                ],
                "url": "https://www.traxo.com/trips/211111111111111111",
                "harvested": true,
                "created": "2008-11-08T09:37:07+0000",
                "updated": "2011-10-26T19:45:51+0000"
            },
            "segment": {
                "id": "533164363472469606",
                "member_id": "111111111111111111",
                "type": "Air",
                "status": "Active",
                "first_name": "Don",
                "last_name": "Draper",
                "airline": "Delta Air Lines",
                "iata_code": "DL",
                "normalized_airline": "DAL",
                "phone": "+1 214 720 2224",
                "flight_num": "1460",
                "seat_assignment": "2C",
                "origin": "DFW",
                "origin_name": "Dallas/Fort Worth International",
                "origin_city_name": "Dallas",
                "origin_admin_code": "TX",
                "origin_country": "US",
                "origin_lat": 32.9000015258789,
                "origin_lon": -97.0500030517578,
                "destination": "SFO",
                "destination_name": "San Francisco International Airport",
                "destination_city_name": "San Francisco",
                "destination_admin_code": "CA",
                "destination_country": "US",
                "destination_lat": 37.6166648864746,
                "destination_lon": -122.383331298828,
                "departure_datetime": "2016-08-13T23:40:00.000Z",
                "departure_time_zone": "CDT",
                "departure_time_zone_id": "America/Chicago",
                "arrival_datetime": "2016-08-14T23:40:00.000Z",
                "arrival_time_zone": "PDT",
                "arrival_time_zone_id": "America/Los_Angeles",
                "confirmation_no": "ABC123",
                "support_phone": "string",
                "support_url": "string",
                "icon_url": "string",
                "image_url": "string",
                "source": "Delta",
                "harvested": true,
                "price": "500.00",
                "currency": "USD",
                "pax_number": 1,
                "booking_agent": "string",
                "ticket_number": "string",
                "class_of_service": "string",
                "meal": "string",
                "stops": "string",
                "duration": "string",
                "equipment_code": "string",
                "equipment_type": "string",
                "departure_terminal": "string",
                "departure_gate": "string",
                "arrival_terminal": "string",
                "arrival_gate": "string",
                "air_notes": "string",
                "created": "2016-07-04T07:00:00+0000",
                "updated": "2016-07-04T09:30:00+0000",
                "metadata": null
            }
        }
    }
}
Example:
{
    "id": "333333333333333333",
    "type": "trip_segment.updated",
    "created": "2017-11-01T01:00:00+00:00",
    "data": {
        "object": {
            "trip": {
                "id": "211111111111111111",
                "member_id": "111111111111111111",
                "status": "Active",
                "destination": "Dallas",
                "admin_code": "TX",
                "country": "US",
                "lat": 32.7830543518066,
                "lon": -96.8066635131836,
                "begin_datetime": "2010-08-13T23:40:00.000Z",
                "end_datetime": "2010-08-14T23:40:00.000Z",
                "duration": "1",
                "distance": "380",
                "personal": 1,
                "business": 1,
                "privacy": "Buddies Only",
                "verified": "Y",
                "headline": "Test trip in Dallas",
                "first_name": "Don",
                "last_name": "Draper",
                "begin_time_zone_id": "America/Chicago",
                "end_time_zone_id": "America/Chicago",
                "begin_time_zone": "CDT",
                "end_time_zone": "CDT",
                "images": [
                    {
                      "prefix": "https://www.traxo.com/images/flags/subdivisions/",
                      "suffix": "/us-ny.png"
                    }
                ],
                "url": "https://www.traxo.com/trips/211111111111111111",
                "harvested": true,
                "created": "2008-11-08T09:37:07+0000",
                "updated": "2011-10-26T19:45:51+0000"
            },
            "segment": {
                "id": "533164363472469606",
                "member_id": "111111111111111111",
                "type": "Air",
                "status": "Active",
                "first_name": "Don",
                "last_name": "Draper",
                "airline": "Delta Air Lines",
                "iata_code": "DL",
                "normalized_airline": "DAL",
                "phone": "+1 214 720 2224",
                "flight_num": "1460",
                "seat_assignment": "2C",
                "origin": "DFW",
                "origin_name": "Dallas/Fort Worth International",
                "origin_city_name": "Dallas",
                "origin_admin_code": "TX",
                "origin_country": "US",
                "origin_lat": 32.9000015258789,
                "origin_lon": -97.0500030517578,
                "destination": "SFO",
                "destination_name": "San Francisco International Airport",
                "destination_city_name": "San Francisco",
                "destination_admin_code": "CA",
                "destination_country": "US",
                "destination_lat": 37.6166648864746,
                "destination_lon": -122.383331298828,
                "departure_datetime": "2016-08-13T23:40:00.000Z",
                "departure_time_zone": "CDT",
                "departure_time_zone_id": "America/Chicago",
                "arrival_datetime": "2016-08-14T23:40:00.000Z",
                "arrival_time_zone": "PDT",
                "arrival_time_zone_id": "America/Los_Angeles",
                "confirmation_no": "ABC123",
                "support_phone": "string",
                "support_url": "string",
                "icon_url": "string",
                "image_url": "string",
                "source": "Delta",
                "harvested": true,
                "price": "500.00",
                "currency": "USD",
                "pax_number": 1,
                "booking_agent": "string",
                "ticket_number": "string",
                "class_of_service": "string",
                "meal": "string",
                "stops": "string",
                "duration": "string",
                "equipment_code": "string",
                "equipment_type": "string",
                "departure_terminal": "string",
                "departure_gate": "string",
                "arrival_terminal": "string",
                "arrival_gate": "string",
                "air_notes": "string",
                "created": "2016-07-04T07:00:00+0000",
                "updated": "2016-07-04T09:30:00+0000",
                "metadata": null
            }
        }
    }
}
Example:
{
    "id": "333333333333333333",
    "type": "trip_segment.added",
    "created": "2017-11-01T01:00:00+00:00",
    "data": {
        "object": {
            "trip": {
                "id": "211111111111111111",
                "member_id": "111111111111111111",
                "status": "Active",
                "destination": "Dallas",
                "admin_code": "TX",
                "country": "US",
                "lat": 32.7830543518066,
                "lon": -96.8066635131836,
                "begin_datetime": "2010-08-13T23:40:00.000Z",
                "end_datetime": "2010-08-14T23:40:00.000Z",
                "duration": "1",
                "distance": "380",
                "personal": 1,
                "business": 1,
                "privacy": "Buddies Only",
                "verified": "Y",
                "headline": "Test trip in Dallas",
                "first_name": "Don",
                "last_name": "Draper",
                "begin_time_zone_id": "America/Chicago",
                "end_time_zone_id": "America/Chicago",
                "begin_time_zone": "CDT",
                "end_time_zone": "CDT",
                "images": [
                    {
                      "prefix": "https://www.traxo.com/images/flags/subdivisions/",
                      "suffix": "/us-ny.png"
                    }
                ],
                "url": "https://www.traxo.com/trips/211111111111111111",
                "harvested": true,
                "created": "2008-11-08T09:37:07+0000",
                "updated": "2011-10-26T19:45:51+0000"
            },
            "segment": {
                "id": "533164363472469606",
                "member_id": "111111111111111111",
                "type": "Air",
                "status": "Active",
                "first_name": "Don",
                "last_name": "Draper",
                "airline": "Delta Air Lines",
                "iata_code": "DL",
                "normalized_airline": "DAL",
                "phone": "+1 214 720 2224",
                "flight_num": "1460",
                "seat_assignment": "2C",
                "origin": "DFW",
                "origin_name": "Dallas/Fort Worth International",
                "origin_city_name": "Dallas",
                "origin_admin_code": "TX",
                "origin_country": "US",
                "origin_lat": 32.9000015258789,
                "origin_lon": -97.0500030517578,
                "destination": "SFO",
                "destination_name": "San Francisco International Airport",
                "destination_city_name": "San Francisco",
                "destination_admin_code": "CA",
                "destination_country": "US",
                "destination_lat": 37.6166648864746,
                "destination_lon": -122.383331298828,
                "departure_datetime": "2016-08-13T23:40:00.000Z",
                "departure_time_zone": "CDT",
                "departure_time_zone_id": "America/Chicago",
                "arrival_datetime": "2016-08-14T23:40:00.000Z",
                "arrival_time_zone": "PDT",
                "arrival_time_zone_id": "America/Los_Angeles",
                "confirmation_no": "ABC123",
                "support_phone": "string",
                "support_url": "string",
                "icon_url": "string",
                "image_url": "string",
                "source": "Delta",
                "harvested": true,
                "price": "500.00",
                "currency": "USD",
                "pax_number": 1,
                "booking_agent": "string",
                "ticket_number": "string",
                "class_of_service": "string",
                "meal": "string",
                "stops": "string",
                "duration": "string",
                "equipment_code": "string",
                "equipment_type": "string",
                "departure_terminal": "string",
                "departure_gate": "string",
                "arrival_terminal": "string",
                "arrival_gate": "string",
                "air_notes": "string",
                "created": "2016-07-04T07:00:00+0000",
                "updated": "2016-07-04T09:30:00+0000",
                "metadata": null
            }
        }
    }
}
Example:
{
    "id": "333333333333333333",
    "type": "trip_segment.removed",
    "created": "2017-11-01T01:00:00+00:00",
    "data": {
        "object": {
            "trip": {
                "id": "211111111111111111",
                "member_id": "111111111111111111",
                "status": "Active",
                "destination": "Dallas",
                "admin_code": "TX",
                "country": "US",
                "lat": 32.7830543518066,
                "lon": -96.8066635131836,
                "begin_datetime": "2010-08-13T23:40:00.000Z",
                "end_datetime": "2010-08-14T23:40:00.000Z",
                "duration": "1",
                "distance": "380",
                "personal": 1,
                "business": 1,
                "privacy": "Buddies Only",
                "verified": "Y",
                "headline": "Test trip in Dallas",
                "first_name": "Don",
                "last_name": "Draper",
                "begin_time_zone_id": "America/Chicago",
                "end_time_zone_id": "America/Chicago",
                "begin_time_zone": "CDT",
                "end_time_zone": "CDT",
                "images": [
                    {
                      "prefix": "https://www.traxo.com/images/flags/subdivisions/",
                      "suffix": "/us-ny.png"
                    }
                ],
                "url": "https://www.traxo.com/trips/211111111111111111",
                "harvested": true,
                "created": "2008-11-08T09:37:07+0000",
                "updated": "2011-10-26T19:45:51+0000"
            },
            "segment": {
                "id": "533164363472469606",
                "member_id": "111111111111111111",
                "type": "Air",
                "status": "Active",
                "first_name": "Don",
                "last_name": "Draper",
                "airline": "Delta Air Lines",
                "iata_code": "DL",
                "normalized_airline": "DAL",
                "phone": "+1 214 720 2224",
                "flight_num": "1460",
                "seat_assignment": "2C",
                "origin": "DFW",
                "origin_name": "Dallas/Fort Worth International",
                "origin_city_name": "Dallas",
                "origin_admin_code": "TX",
                "origin_country": "US",
                "origin_lat": 32.9000015258789,
                "origin_lon": -97.0500030517578,
                "destination": "SFO",
                "destination_name": "San Francisco International Airport",
                "destination_city_name": "San Francisco",
                "destination_admin_code": "CA",
                "destination_country": "US",
                "destination_lat": 37.6166648864746,
                "destination_lon": -122.383331298828,
                "departure_datetime": "2016-08-13T23:40:00.000Z",
                "departure_time_zone": "CDT",
                "departure_time_zone_id": "America/Chicago",
                "arrival_datetime": "2016-08-14T23:40:00.000Z",
                "arrival_time_zone": "PDT",
                "arrival_time_zone_id": "America/Los_Angeles",
                "confirmation_no": "ABC123",
                "support_phone": "string",
                "support_url": "string",
                "icon_url": "string",
                "image_url": "string",
                "source": "Delta",
                "harvested": true,
                "price": "500.00",
                "currency": "USD",
                "pax_number": 1,
                "booking_agent": "string",
                "ticket_number": "string",
                "class_of_service": "string",
                "meal": "string",
                "stops": "string",
                "duration": "string",
                "equipment_code": "string",
                "equipment_type": "string",
                "departure_terminal": "string",
                "departure_gate": "string",
                "arrival_terminal": "string",
                "arrival_gate": "string",
                "air_notes": "string",
                "created": "2016-07-04T07:00:00+0000",
                "updated": "2016-07-04T09:30:00+0000",
                "metadata": null
            }
        }
    }
}

Segment Events

Segment events can be used to monitor a specific mode of travel. Most consumers should opt for the trip events listed above.

Event Description
air_segment.created Triggered when an air segment is created.
air_segment.updated Triggered when an air segment is updated or deleted.
car_segment.created Triggered when an air segment is created.
car_segment.updated Triggered when a car segment is updated or deleted.
hotel_segment.created Triggered when a hotel segment is created.
hotel_segment.updated Triggered when a hotel segment is updated or deleted.
rail_segment.created Triggered when a rail segment is created.
rail_segment.updated Triggered when a rail segment is updated or deleted.
cruise_segment.created Triggered when a cruise segment is created.
cruise_segment.updated Triggered when a cruise segment is updated or deleted.
activity_segment.created Triggered when an activity segment is created.
activity_segment.updated Triggered when an activity segment is updated or deleted.

Email Parsing Events

Email parsing events are emitted for each email sent to Traxo for parsing.

Event Description
email.created Triggered when an email is received by Traxo for parsing.
email.updated Triggered when an email is updated during processing and upon reaching a final state.

Enabling Webhooks

Webhooks are enabled by calling the /v2/callbacks endpoint with the appplication's client credentials as shown in the API explorer.

Once this setting is saved, the application will immediately begin receiving applicable events.

A valid SSL-certificate and properly configured webserver is required for all production applications.

The registered webhooks URL may include query parameters that are required for your application as shown in the example.

Please contact api-support@traxo.com if your Webhooks URL uses a non-standard TCP port or you need additional assistance configuration your application.

Authentication

A webhooks url may be protected via HTTP Basic authentication by registering the callbacks url with embedded credentials.

Specify the username and password as shown:

https://username:secretpassword@www.example.com/webcallback?foo=bar
Alternatively, base64 encoded credentials (as "username:password") can be provided per RFC2617:
https://ENCODED-CREDENTIALS@www.example.com/webcallback?foo=bar

Receiving Webhooks

Registered URLs will receive webhooks for each supported event occurring within a Traxo member account that has authorized the application (via OAuth, etc). Applications will not receive webhooks for Traxo members that are not users of that application.

Upon receipt of a webhooks POST, the application server should immediately respond with a HTTP 200-series status code. It must respond within 5 seconds. A task queue is recommended for any significant processing of the response that could delay responding to the webhooks server.

The webhooks payload contains a JSON object containing specific information about the event and the same response for a given object as would be obtained by calling the Traxo API directly for the same object. See the example below.

Example (object is truncated for readability):

{
  "id": "441423047655159816",
  "type": "trip.updated",
  "created": "2013-08-08T11:20:00+00:00",
  "data": {
    "object": {
      "id": "1234",
      "member_id": "5678",
      "headline": "Trip to Hawaii",
      ....
    }
  }
}

Retries

If your application is not available or fails to return the appropriate HTTP 200-series status code in time, the delivery will be retried each hour for approximately 48 hours. After this time, the delivery will be marked as "Failed" by the system.

Selectors

If an application only consumes certain events, the types of events sent to a callback can be customized. Events that are not relevant to the application will not be sent. This reduces load on the application's webhooks handler and increases the timeliness of delivery for the events that the application cares about.

Events to be sent can be customized by appending the "events" query parameter followed by one or more of the supported event names or types separated by commas to the webhooks URL registered with Traxo for your API client.

Example:

https://example.com?events=trip,trip_segment,email

This example shows how an application would receive "trip", "trip_segment", and "email" events, but no other types of events. In this example, segment level events ("air_segment.*", "hotel_segment.*, etc) are not needed and not used by the application and are not transmitted.

Example:

https://example.com?events=trip.created,email

This example shows that specific events (i.e. "created") within a type ("trip") can be specified. The application in this case would be notified about trips that are created, but not about updates to those trips, so this use case is likely very specific to the application itself.

Modifiers

Depending on the application, more or less payload data may be desirable.

The payload data can be altered by appending the "data" query parameter followed by one or more of the supported modifiers separated by commas to the webhooks URL registered with Traxo for your API client.

All modifiers are optional and independent. If the "data" query parameter is supplied, one or more modifiers should be used. If no "data" query parameter is supplied, the standard response includes the "object".

Example:

https://example.com?data=id,object,owner

Using this example webhooks url, the response would include the ID of the changed object, the changed object itself, a compact member object, an array of parent objects (when applicable), and an array of child objects (when applicable).

Consumers should only request data that will actually be used. If only the ID of the object associated with an event is needed, use "?data=id". Additional details may be fetched via ID from the Traxo API as they are needed.

Example (some objects truncated for readability):

{
  "id": "441423047655159818",
  "type": "trip.created",
  "created": "2013-08-08T11:20:00+00:00",
  "data": {
    "id": "1234",
    "object": {
      "id": "1234",
      "member_id": "5678",
      ....
    },
    "owner": {
      "id": "5678",
      "first_name": "Don",
      "last_name": "Draper",
      "email": "don@example.com",
      "travel_score": "95"
    }
  }
}

Implementation Notes