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":
Next, activate the "Add a new Hook" button. A new page will appear with a form on it:
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:
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.
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:
- 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.
This is a full example of what a POSTed web hook will look like: