# Webhook integration

As our payloads for Zapier Webhooks and custom webhooks will be the same, we kindly refer you to our [Zapier instructions](/md/help-center/apis/apps/zapier/). 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](/md/help-center/apis/apps/apps-and-users/).

### 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](/help-center/privacy-security/monitoring/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](/help-center/monitoring/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](/help-center/monitoring/getting-started/adding-pages/):

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](/help-center/monitoring/getting-started/invite-users/):

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](/help-center/privacy-security/monitoring/javascript-integrity/) 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:

webhook-domain-snippet-hash.json

```json
{
  "type": "domain",
  "entity": "snippet",
  "action": "hash",
  "domain": "rumvision.com",
  "by": "info@example.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](/help-center/privacy-security/monitoring/javascript-integrity/#consequence-of).
- `link`  
   A permanent link for this domain containing the latest embed code

Last changed 8 April 2024
