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."

Supported Events

Enabling Webhooks

Webhooks are typically enabled via the Developer Portal by setting a valid callback URL in the "Webhooks URL" parameter of an application. Once this setting is saved, the application will immediately begin receiving applicable events.

An alternative method to add one or more webhooks URLs is by calling the /v2/callbacks endpoint with the appplication's client credentials as shown in the API explorer.

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.

To quickly setup a webhooks receiver for testing, Traxo recommends RequestBin. RequestBin gives you a URL that will collect requests made to it and let you inspect them in a human-friendly way for up to 24 hours.

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.

Custom Payload Data

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 selected separated by commas to the webhooks URL registered with Traxo for your API client.

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

Selectors

Example (all selectors shown for completeness):

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

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).

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.

Segment Event Example (some objects truncated for readability):

{
  "id": "441423047655159817",
  "type": "air_segment.updated",
  "created": "2013-08-08T11:20:00+00:00",
  "data": {
    "id": "1234",
    "object": {
      "id": "1234",
      "member_id": "5678",
      "type": "Air",
      ....
    },
    "owner": {
      "id": "5678",
      "first_name": "Don",
      "last_name": "Draper",
      "email": "don@example.com",
      "travel_score": "95"
    },
    "parents": [
      {
        "trip": {
          ....
        }
      }
    ],
    "children":[
    ]
  }
}

Trip Event 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"
    },
    "parents": [
    ],
    "children": {
      "segments": [
        {
          "id": "3124",
          "type: "Air",
          "airline": "JetBlue",
          ....
        }
      ]
    }
  }
}

Implementation Notes