Skip to main content
Webhooks

API callbacks via webhook reporters

I
Written by Igor Ivanovski
Updated over a week ago

Webhooks are a tool that allows you to get notified of a specific event that occurs within the Usetrace system through payloads that are POSTed to a specific URL. Together with the other type of reporters and result API endpoints, they help to keep you up-to-date with your builds and suit better in asynchronous pipelines, where polling is not a good approach.

Currently, they are 2 endpoints that are supported and can accept a webhook payload URL, on which they will post results. Those are the trace execute and the project execute-all commands.

POST https://api.usetrace.com/api/trace/<TRACE_ID>/execute

POST https://api.usetrace.com/api/project/<PROJECT_ID>/execute-all

Example POST payload:


{
"requiredCapabilities": [
{"browserName": "chrome"},
{"browserName": "firefox"}
],
"reporters": [
{
"webhook": {
"url": "<WEBHOOK_URL>",
"when": "<always|fails|changes",
"secretKey": "<HMAC_SECRET_KEY>",
"username": "<AUTH_USERNAME>",
"password": "<AUTH_PASSWORD>"
}
}
]
}

The payload should consist of one or more webhook reporter objects within the reporters array.

Required arguments:

  • url: string containing the destination for the callback POST response

  • when: string designation when the webhook should be triggered. Available values: always, fails (on failures only), changes (on result changes only)

Optional arguments:

  • secretKey: string if provided, a HMAC signature will be created and passed via a Signature header in order to verify the validity of the POST response payload

  • username: string, if provided together with the password, Authorization header, will be responded back, if your callback URL is behind authwall. Currently, only Basic Auth is supported

  • password: string the password of the basic auth

Example payload response:

{
"name": "Environment: http://testsite.usetrace.com/",
"tests": 4,
"traces": 2,
"expectedTracesToPass": 2,
"tracesPassed": 1,
"errors": 1,
"failures": 1,
"skip": 0,
"bugs": 0,
"bugsPassing": 0,
"buildStable": false,
"testCase": [
{
"className": "Usetrace.trace",
"name": "chrome: Trace 1",
"time": 61.755,
"error": {
"type": "error",
"message": "Timeout opening the email client\n\nDetails: http://team.qa.usetrace.com/editor/#trace/X9eCbhujPABldBzEv7E3iTzh07BweZgi/result/YiiqRftfHwAZzmfmzb8mSFJfPYSdicaB\nScreenshot: http://team.qa.usetrace.com/screen/X9eCbBujPABldBzDEUdS_fVhlzJwTJHO/YiiqRftfHwAZzmfklw7vDvc7AXmDz-2a/YiiqRftfHwAZzmfmzb8mSFJfPYSdicaB/full.png"
}
},
{
"className": "Usetrace.trace",
"name": "chrome: Trace 2",
"time": 0.289,
"error": null
},
{
"className": "Usetrace.trace",
"name": "firefox: Trace 1",
"time": 62.051,
"error": {
"type": "error",
"message": "Timeout opening the email client\n\nDetails: http://team.qa.usetrace.com/editor/#trace/X9eCbhujPABldBzEv7E3iTzh07BweZgi/result/YiiqRftfHwAZzmfnjQ2MD01pAp1_QEyi\nScreenshot: http://team.qa.usetrace.com/screen/X9eCbBujPABldBzDEUdS_fVhlzJwTJHO/YiiqRftfHwAZzmfklw7vDvc7AXmDz-2a/YiiqRftfHwAZzmfnjQ2MD01pAp1_QEyi/full.png"
}
},
{
"className": "Usetrace.trace",
"name": "firefox: Trace 2",
"time": 0.37,
"error": null
}
]
}
Did this answer your question?