Web Hooks

Web hooks allow you to receive announcement about specific events that have occurred on an external service. For Tenon, we will send you announcements about things like new projects and new reports. We refer to these things as objects.

The way that web hooks work is simple: We send an HTTP POST request to the endpoint you've set up above. The POST body contains JSON data that your endpoint then processes however you see fit. For example, you can set up a web hook to receive all new test runs and then save that data somewhere as a full log aggregation of your test activity.

Events that webhooks will announce:

  • Created - A resource was created
  • Updated - A resource was updated
  • Deleted - A resource was deleted

Setting up web hooks

In order to start receiving web hook data you need to register an endpoint. You can register as many web hooks as you need. Once registered, we will begin POSTing data to the endpoint you set. Log in and navigate to "Settings", then select the link labelled "Web Hooks".

Screenshot of the landing page for web hooks, without any registered hooks

Next, activate the "Add a new Hook" button. A new page will appear with a form on it

Screenshot of the form for adding hooks

The following fields appear:

  • Name - Enter a name for this web hook so you can remember what it is about later.
  • URL for the Hook Location - Enter the fully-qualified URL to which we'll be POSTing the data. This must be a valid URL.
  • A series of checkboxes under the label "Which objects should Post to this hook?" - select the checkboxes for which objects you want to receive data.

Enter the relevant data in the form and activate the "Submit Hook" button.

Screenshot of the landing page for web hooks, with the newly registered hook

Once registered, we will begin posting data to the hooks.

Web hook structures

We have a JSON Schema file available on Github. The JSON Schema file represents the structure of webhook data that will be POSTed to customers' endpoints from Tenon.io. The type of data that is sent back will depend on the nature of the event that was triggered and the type of object which experienced the event. We will send over a JSON POST body with the following details:

  • eventID - Globally unique identifier for the event instance.
  • event - Token string representing the type of event this was. The event is structured as object.event, i.e. site.created
  • dateAdded - Unix datetime representing the time, in GMT, when the event occurred.
  • data - Object containing details relevant to the type of object the event applies to. The content depends on the type of object and is described below.

Objects

The following objects are eligible for event announcements via web hooks at this time.

  • Test runs: identified as apiLog objects
  • Projects: identified as project objects
  • Site monitors: identified as site objects

A description of what each of these data objects will look like is shown below:

Test Runs

  • Note 1: This hook type is only created when new test runs occur. There are no 'updated' or 'deleted' events for test runs
  • Note 2: This hook includes the full API response

{
  "object": "apiLog",
  "responseID": "3b5cd94abefb1ad78a34c36c1dfbbddb",    
  "dateAdded": 1480977198796,
  "status": "200",
  "message": "Success",
  "reqLevel": "AAA",
  "reqCertainty": 0,
  "reqPriority": 0,
  "docID": "AA1E7671-2DA5-EA5D-2C84-600DFF10967F",
  "documentSize": 41093,
  "sourceHash": "96e3e105ef2a286bbec954005deed619",
  "errorDensity": 30,
  "warningDensity": 0,
  "allDensity": 30,
  "errors": 12,
  "warnings": 0,
  "url": "https://www.example.com",
  "fragment": 0,  
  "store": 1,
  "projectID":"cc5ec01f-14d6-4d9b-8229-9fe17b618f1e",
  "viewPortWidth": 1024,
  "viewPortHeight": 768,
  "uaString":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/40.0.2214.111 Safari/537.36",
  "startTime": 1480977198796,
  "endTime": 1480977302258,
  "true_http_code": 200,
  "delay": 2000,  
  "issuesByLevelA": 11,
  "issuesByLevelAA": 1,
  "issuesByLevelAAA": 9, 
  "testsFailing": 5,
  "testsPassing": 57,
  "pageTitle": "Example",
  "fullResponse": {} // full copy of API response.
}

Projects


{
  "object": "project", 
  "projectID": "cc5ec01f-14d6-4d9b-8229-9fe17b618f1e",    
  "name": "Awesome Project",    
  "description": "Project to do testing of my awesome website",   
  "dateAdded": 1480977198796,  
  "lastmod": 1480977198796,  
  "defaultItem": 1,     
  "apiDefaultCertainty": 0,    
  "apiDefaultLevel": "AAA",
  "apiDefaultPriority": 0,    
  "apiDefaultStore": 1,     
  "apiDefaultUAString": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/40.0.2214.111 Safari/537.36",
  "apiDefaultViewportHeight": 768,
  "apiDefaultViewportWidth": 1024  
}

Site Monitors


{
  "object": "site",
  "name": "My Example Site",
  "siteKey": "11jyv9d1NEnY",
  "projectID": "cc5ec01f-14d6-4d9b-8229-9fe17b618f1e",
  "siteUrl": "http://www.example.com"
}

Full Example

This is a full example of what a POSTed web hook will look like


{
  "eventID": "eb14b5be-2520-43e1-8398-0c40a7caeca9",
  "event": "site.created",
  "dateAdded": 1480977198796,
  "data": {
    "object": "site",
    "name": "My Example Site",
    "siteKey": "11jyv9d1NEnY",
    "projectID": "cc5ec01f-14d6-4d9b-8229-9fe17b618f1e",
    "siteUrl": "http://www.example.com"
  }
}