Webhooks Documentation

Below are the descriptions of each attribute in the delivered JSON. Want more info on the downloaded files? A manifest README.txt is included in every zip download of version-specific data. To obtain these, navigate to the “page view” for any monitored URL. There, look for the down arrow icon that will initiate the zip download. The README in that folder provides more details on each file.

• url: Specific monitored URL where a change has been detected.
• capturedAt: Timestamp of when this version was captured.
• comparisonType: Comparison type as established in session settings; can be: HTML / visual / text / network.
• orgId: ID of your team in our system.
• orgName: The name of your team, if it has one.
• title: Title of the page, if it has one.
• statusCode: HTTP status code; usually 200, meaning success.
• finalUrl: If the page redirects to a different URL, this value will be present as the final URL redirected to.

• aiFlagged: Fluxguard AI evaluates the text changes and adds a flag, either “warning” for significant changes or “serenity” if they appear unimportant.

• summary: If enabled, a Fluxguard AI-generated summary of the text of the version.

• diffSummary: If enabled, a Fluxguard AI-generated summary of the difference from the previous version’s text.

• site:
  • id: ID of the site in our system.
  • origin: Root monitored domain.

• session:
  • id: ID of the session in our system.
  • name: Name of the session.

• alarms: an optional array of configurable alarms that you may have created. Each alarm object includes at minimum a name and value.
• page:
  • id: ID of the page in our system.
  • path: Path of monitored page.

• fileBaseUrl: Base URL to AWS S3 location for all referenced files. This is the prefix to use when appending filenames as specified in files.captures and files.diffs below. That is to say, use this string as the prefix, and append one of the filenames referenced below as the suffix.

• files: This object contains two additional items – captures and diffs – that refer to the core version and difference files. In general, you want to automate the download of these files into your system.

• • captures: These referenced files constitute the core data for this captured version. Moreover, these files serve as input to our difference engines in determining if a change has transpired.
    • html: The rendered DOM for the version.
    • visual: The full-size screenshot of this version. This will often be compareTarget.png. Note that there are usually clipped medium and small versions of this screenshot. These can be obtained by appending _md and _sm after the filename (i.e., compareTarget_md.png and compareTarget_sm.png thereafter).
    • txt: The extracted text for this version.
    • net: The complete HAR file that includes all network activity for this version.
    • nlp: If enabled, the Natural Language Processing JSON for this version.
    • extraData: A JSON document with miscellaneous extra data collected during the crawl, such as cookies, storage, console output, and so on.

• • diffs: These files are often the most critical elements in the JSON. Not only do they reference the key difference files, but their presence or absence indicates whether or not that particular difference was triggered. For example, to the extent that a visual is missing from this object, then no visual difference was detected in this version, and so on.
    • visual: Red-lined visual difference. The absence of this file indicates no visual difference was detected. If present, also try medium and small clipped versions at compareTarget_diff_md.png and compareTarget_diff_sm.png.
    • net: At the present time, this is a true or false value to indicate if a network change was identified.
    • txt: This file is a merging of this version’s text with the previous version’s text. Deletions and additions are highlighted with HTML tags. To view this content in a browser for a color-coded exploration of this data, change the extension to .html. It does not include line breaks, however.You can also try mergedSquashedTextComparison.html. This is akin to the file mentioned above, except it is “squashed.” That means the unchanged text from the comparison was deleted, and changed text is provided for the most part. This makes it simpler to locate changes in longer documents.
    • html: This file is a merging of this version’s HTML with the previous version’s HTML. Deletions and additions are highlighted within the HTML in comments such as <!--fluxguard_added-->this is added text</--fluxguard_added>. This file is best read in an HTML editor versus loading the HTML itself because the actual changes will not be visualized as they are marked by (indiscernible) HTML comments.You can also try mergedSquashedComparison.html, which is similar except the unchanged HTML was removed.You might also try mergedSquashedComparison_escaped.html, which is similar except we “escape” HTML characters. This makes the file suitable to explore HTML changes in the context of a web browser.

• diffUrl: The Fluxguard URL to see the specific version details and differences from the last version. Login, of course, required.
• siteCategories: Any site categories assigned to this site.
• pageCategories: Any page categories assigned to this page.

3.Use Site Categories to restrict pushes to particular sets of sites

As an option, you can add Site Categories to your account. Then, it is possible to assign sites to different categories.

Once you’ve accomplished this, as seen in the screenshot above, you can then limit when Fluxguard pushes to the Webhook endpoint.

4.(Optional) Use a secret key to authenticate webhook data

Each webhook URL has an associated secret key. This can be used to authenticate the data and thus guard against malicious actors sending false webhooks to your server. If this is not a concern, this step can be skipped.

You can click on the key icon to the right of the webhook URL to retrieve the secret. Once in hand, the HMAC algorithm is used to check the HTTP request. There will be a header fluxguard-signature that looks like this:

fluxguard-signature: t=1234567890,v1=0a1b2c3d4e5f6a7b8c9d…

The t represents a timestamp in seconds since January 1, 1970. The v1 is a hexadecimal representation of an HMAC signature using SHA-256. It uses the secret key to sign the string consisting of the value of t, a period ., and the body of the webhook (which will be in JSON). For example, if the body is {"sample":"data"}, then the string encrypted is 1234567890.{"sample":"data"}.

Here is example code for verifying the data using Javascript; headers and body are the headers and body from the incoming webhook, and secret is the secret: