Webhook integration

As our payloads for Zapier Webhooks and custom webhooks will be the same, we kindly refer you to our Zapier instructions. When doing so, you're safe to ignore all mentions of Zapier and ignore the whole "Configuring Zapier" section.

This section will soon elaborate on the JSON payload formats for different message types. Payloads will be the same for Zapier and custom webhooks.

The basics

This chapter will explain general information regarding webhooks that RUMvision will end up calling.

Permissions

It's important to note that the information that is being shared to webhook URLs is restricted based on the permissions of the user that the webhook is associated with. For example, the webhook won't receive data from domains that its user doesn't have access to. And if a user does have access to a domain but not its users nor URLs, changes to users or URLs won't be shared either.

See also: Permissions of an app.

Key information

Data will be send as a (Content-Type) application/json payloads using the POST method. Each payload should at least contain the following information in the :

  • type
  • entity
  • action
  • by

The following chapters will explain what they are exposing.

Other information that will be available within most payloads are as following:

  • domain
    The domain name that the mutated snippet, url of user belongs to.
  • subject
    The subject in human readable format. This can be used to pre-fill your follow-up (Zapier) actions.
  • msg
    A human readable description of the mutation. This can be used to pre-fill your follow-up (Zapier) actions.

Other fields depend on the notification type and entity.

Query string data

However, to simplify webhook efforts on your end, some information is also being shared in the query string of the URL. These are the fields that could become part of the query string:

  • type
    This represents the notification-type (alerts, changelog, competitors, conversations, domain, invoices, profile)
  • entity
    This represents the entity type (domain, snippet, url, user)
  • action
    This represents the type of action (insert, update, delete or hash)
  • domain
    Specific to domain-related changes (such as domain, snippet, urls), this will contain the domain where the change was done
  • number
    Specific to invoices, this will contain the invoice number

This means that the URL of a get request could look like the following:

https://hooks.zapier.com/hooks/catch/12345678/abcdefg/?type=changelog&entity=snippet&action=update&domain=rumvision.com

Deprecated fields

In an earlier version, the following would become part of the query string as well:

  • by
    This represents the user that triggered the change (containing the e-mail address as known within RUMvision)
  • user
    Specific to user management changes (adding, changing or removing a user account), this will contain the user that was subject to a mutation

However, these are removed for privacy reasons as servers are typically logging requests including their query strings. Sending personally identifiable information (PII data) in the request URL would then end up in this PII data being stored in server logs by default.

Do note that this information is in fact still part of the JSON payload in the posted information.

Changelog

Any changes that are being made will be communicated as type: changelog. The field entity will represent what was involved while action will expose what happened.

For example, when changes are made in your domain's snippet configuration, snippet will be used as entity.

Snippet

The payload below represents an update to the tracking snippet configuration.

{
  "type": "changelog",
  "entity": "snippet",
  "action": "update",
  "domain": "rumvision.com",
  "by": "info op rumvision punt com",
  "link": "https://insights.rumvision.com/your-embed/code.txt",
  "diff": {
    "track_element": {
      "old": null,
      "new": 1
    },
    "track_loaf": {
      "old": null,
      "new": 1
    }
  },
  "subject": "rumvision.com: tracking configuration",
  "msg": "info op rumvision punt com changed tracking configuration of rumvision.com:\n• track_element: 1\n• track_loaf: 1\n \n\nSee https://insights.rumvision.com/logs/rumvision.com/snippet/"
}

Fields specific to this payload are:

  • link
    A permanent link for this domain containing the latest embed code
  • diff
    Differences between the previous state of the settings and the new state after the action was performed by the user

Url

The payload below represents mutations within your URL management:

{
  "type": "changelog",
  "entity": "url",
  "action": "update",
  "domain": "rumvision.com",
  "by": "info op rumvision punt com",
  "template": "Blog",
  "url": "https://www.rumvision.com/blog/",
  "diff": {
    "pagetype": "Blog"
  },
  "subject": "rumvision.com: url changed",
  "msg": "info op rumvision punt com made a url change on rumvision.com. Changes:\n• pagetype: References\n\nSee https://insights.rumvision.com/urls/rumvision.com/changelog/"
}

Fields specific to this payload are:

  • template
    The template name
  • url
    The URL (rule): an absolute URL, regular expression of CSS selector
  • diff
    This contains the fields that were changed.

User

The payload below represents mutations within your added users:

{
  "type": "changelog",
  "entity": "user",
  "action": "insert",
  "domain": "rumvision.com",
  "by": "info op rumvision punt com",
  "user": "invited op example punt com",
  "diff": {
    "view": {
      "value": 1,
      "action": 1
    },
    "settings": {
      "value": 1,
      "action": 1
    },
    "urls": {
      "value": 0,
      "action": 0
    },
    "users": {
      "value": 0,
      "action": 0
    }
  },
  "subject": "rumvision.com: user added",
  "msg": "info op rumvision punt com added a new user invited op example punt com to domain rumvision.com with the following rights:\n\n• monitoring was added\n• settings was added\n• urls disabled (unchanged)\n• users disabled (unchanged)"
}

Fields specific to this payload are:

  • user
    The user that was affected with the mutation (either added, changed or deleted).
  • diff
    Differences between the previous state of the permissions and the new state after the action was performed.
    The value key represents the current value after the mutation while the action key represents if that permission was added (1), unchanged (0) or removed (-1).

Domains

Direct changes within your domain's security settings will be communicated as type: domains. This also applies when your JavaScript integrity hash is being changed. For examply directly by switching to a different hashing-type or when there were changes in your configuration that forced the hash to change.

Domain snippet hash

An example of a payload when the hash of your snippet hash changed:

{
  "type": "domain",
  "entity": "snippet",
  "action": "hash",
  "domain": "rumvision.com",
  "by": "info op example punt com",
  "hash": "sha512-1CjWdb3m01cPTlYnfSlUwd2X7pFyes/UuWSFO0EKCZM9FG7zaS6TmHqRHmR+Z8kX7503j7o7cUnlHt32nn5tPA==",
  "previous": "sha256-a+YsmZz0k/bIAVY02Pj9Gk6yOjSuZPaxYi9PflFAuwo=",
  "link": "https://insights.rumvision.com/your-embed/code.txt",
  "subject": "example.com: SRI tracking hash changed",
  "msg": "• old hash: sha256-a+YsmZz0k/bIAVY02Pj9Gk6yOjSuZPaxYi9PflFAuwo=\n• new hash: sha512-1CjWdb3m01cPTlYnfSlUwd2X7pFyes/UuWSFO0EKCZM9FG7zaS6TmHqRHmR+Z8kX7503j7o7cUnlHt32nn5tPA==\n\nFind documentation and latest snippet at https://www.rumvision.com/help-center/privacy-security/monitoring/javascript-integrity/#updating-the and https://insights.rumvision.com/your-embed/code.txt"
}

Fields specific to this payload are:

  • hash
    The new hash, always starting with sha.
  • previous
    The most recent hash just before this change. Do note that this might not always be equal to your most recently deployed hash as multiple changed might be done in a short timespan, resulting in multiple hashes being generated.
    Read more about the consequence of a new hash.
  • link
    A permanent link for this domain containing the latest embed code

Table of Contents