Webhooks | Usetrace Help Center

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
    }
  ]
}