# Webhook events and payloads

You can create webhooks that subscribe to the events listed on this page. Each webhook event includes a description of the webhook properties and an example payload. For more information, see "Creating webhooks."

# Webhook payload object common properties

Each webhook event payload also contains meta properties unique to the event.

Key	Type	Description
`trigger`	`string`	Most webhook payloads contain an `trigger` property that contains the specific activity that triggered the event.
`group`	`object`	A group object containing the name and unique slug (id) of the group
`group.name`	`string`	Display friendly name of the group
`group.slug`	`string`	A unique url friendly short id of the group
`data`	`object`	The webhook payload body. See schema or an example payload.

Note: Payloads are capped at 25 MB. If your event generates a larger payload, a webhook will not be fired. This may happen, for example, on a event trigger if the navigational history is too large. We suggest monitoring your payload size to ensure delivery.

# Delivery headers

HTTP POST payloads that are delivered to your webhook's configured URL endpoint will contain several special headers:

Header	Description
`X-Airlock-Group`	A unique url friendly short id of the group.
`X-Airlock-Trigger`	Name of the event that triggered the delivery.
`X-Airlock-Signature`	This is the HMAC hex digest of the request body, and is generated using the SHA-256 hash function and the `secret` as the HMAC `key`.

# Example delivery

> POST /payload HTTP/2

> Host: localhost:4567
> X-Airlock-Signature: sha256=d57c68ca6f92289e6987922ff26938930f6e66a2d161ef06abdf1859230aa23c
> Content-Type: application/json
> Content-Length: 6615
> X-GitHub-Trigger: event
> X-GitHub-Group: devs-europe

> {
>   "trigger": "event",
>   "group": {
>     "name": "Devs team in Europe",
>     "slug": "devs-europe",
>   },
>   "data" : {
>     "sdk": "Airlock v1",
>     "level": "high",
>     "user": {
>       "id": 1,
>       ...
>     },
> }

# Configuration Requirements

One URL webhook per group
URL from a verified domain in the organization
URL with a valid SSL certificate

# Webhook payload schema

Below is the schema for the data attribute in the payload.

{
  "type": "object",
  "properties": {
    "sdk": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "version": {
          "type": "string"
        },
        "packages": {
          "type": "array",
          "items": [
            {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "version": {
                  "type": "string"
                }
              },
              "required": [
                "name",
                "version"
              ]
            }
          ]
        },
        "integrations": {
          "type": "array",
          "items": [
            {
              "type": "string"
            },
            {
              "type": "string"
            },
            {
              "type": "string"
            },
            {
              "type": "string"
            },
            {
              "type": "string"
            },
            {
              "type": "string"
            },
            {
              "type": "string"
            }
          ]
        }
      },
      "required": [
        "name",
        "version",
        "packages",
        "integrations"
      ]
    },
    "tags": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string"
        },
        "reason": {
          "type": "string"
        },
        "browserExtensions": {
          "type": "string"
        }
      },
      "required": [
        "url",
        "reason",
        "browserExtensions"
      ]
    },
    "user": {
      "type": "object",
      "properties": {
        "ip": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "email": {
          "type": "string"
        },
        "geolocation": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string"
            },
            "country": {
              "type": "string"
            },
            "latitude": {
              "type": "number"
            },
            "province": {
              "type": "string"
            },
            "longitude": {
              "type": "number"
            }
          },
          "required": [
            "city",
            "country",
            "latitude",
            "province",
            "longitude"
          ]
        }
      },
      "required": [
        "ip",
        "name",
        "email",
        "geolocation"
      ]
    },
    "level": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "release": {
      "type": "string"
    },
    "request": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string"
        },
        "headers": {
          "type": "object",
          "properties": {
            "User-Agent": {
              "type": "string"
            }
          },
          "required": [
            "User-Agent"
          ]
        },
        "categories": {
          "type": "array",
          "items": {}
        }
      },
      "required": [
        "url",
        "headers",
        "categories"
      ]
    },
    "event_id": {
      "type": "string"
    },
    "platform": {
      "type": "string"
    },
    "timestamp": {
      "type": "number"
    },
    "breadcrumbs": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "properties": {
            "data": {
              "type": "object",
              "properties": {
                "tab": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer"
                    },
                    "favicon": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "favicon"
                  ]
                }
              },
              "required": [
                "tab"
              ]
            },
            "message": {
              "type": "string"
            },
            "category": {
              "type": "string"
            },
            "timestamp": {
              "type": "number"
            }
          },
          "required": [
            "data",
            "message",
            "category",
            "timestamp"
          ]
        },
        {
          "type": "object",
          "properties": {
            "data": {
              "type": "object",
              "properties": {
                "tab": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer"
                    },
                    "favicon": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "favicon"
                  ]
                }
              },
              "required": [
                "tab"
              ]
            },
            "message": {
              "type": "string"
            },
            "category": {
              "type": "string"
            },
            "timestamp": {
              "type": "number"
            }
          },
          "required": [
            "data",
            "message",
            "category",
            "timestamp"
          ]
        },
        {
          "type": "object",
          "properties": {
            "data": {
              "type": "object",
              "properties": {
                "tab": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer"
                    },
                    "favicon": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "favicon"
                  ]
                }
              },
              "required": [
                "tab"
              ]
            },
            "message": {
              "type": "string"
            },
            "category": {
              "type": "string"
            },
            "timestamp": {
              "type": "number"
            }
          },
          "required": [
            "data",
            "message",
            "category",
            "timestamp"
          ]
        }
      ]
    },
    "environment": {
      "type": "string"
    },
    "fingerprint": {
      "type": "array",
      "items": [
        {
          "type": "string"
        }
      ]
    }
  },
  "required": [
    "sdk",
    "tags",
    "user",
    "level",
    "message",
    "release",
    "request",
    "event_id",
    "platform",
    "timestamp",
    "breadcrumbs",
    "environment",
    "fingerprint"
  ]
}

# Webhook payload example

Below is an example of the data attribute in the payload.

{
  "sdk": {
    "name": "airlock.javascript.browser",
    "version": "5.29.2",
    "packages": [
      {
        "name": "npm:@airlock/browser",
        "version": "5.29.2"
      }
    ],
    "integrations": [
      "InboundFilters",
      "FunctionToString",
      "TryCatch",
      "Breadcrumbs",
      "GlobalHandlers",
      "LinkedErrors",
      "UserAgent"
    ]
  },
  "tags": {
    "url": "https://www.google.com/search?q=audio+html&oq=audio+html&aqs=chrome.0.0i512l7j69i60.2737j0j7&sourceid=chrome&ie=UTF-8",
    "reason": "The user navigated to the website",
    "browserExtensions": "Phantom,airlock,Google Docs Offline,Merge Windows,Vue.js devtools,Storage Area Explorer"
  },
  "user": {
    "ip": "157.245.72.187",
    "name": "Rick Sanchez",
    "email": "rick.sanchez@morty.com",
    "geolocation": {
      "city": "San Francisco",
      "country": "US",
      "latitude": 37.751,
      "province": "CA",
      "longitude": -97.822
    }
  },
  "level": "visit",
  "message": "Visited www.google.com",
  "release": "airlock@2.0.3",
  "request": {
    "url": "https://www.google.com/search?q=audio+html&oq=audio+html&aqs=chrome.0.0i512l7j69i60.2737j0j7&sourceid=chrome&ie=UTF-8",
    "headers": {
      "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.81 Safari/537.36"
    },
    "categories": []
  },
  "event_id": "2bb48573f538409896e0b371451d523c",
  "platform": "javascript",
  "timestamp": 1634456196.921,
  "breadcrumbs": [
    {
      "data": {
        "tab": {
          "id": 307,
          "favicon": "https://images.immediate.co.uk/production/volatile/sites/4/2019/05/cropped-favicon-bw-f76d239-1e7f748.png?quality=90&resize=32,32"
        }
      },
      "message": "POST https://tps20513.doubleverify.com/bsevent.gif?impid=ff4f58c8c4274a1a932f329342d39893&mascid=kuuwuv56emg7xnafqdt8pjvruswqcn4p&dvp_masver=6&dvp_tisf=1&dvp_t1stMsgB=345&cbust=1634455930388534",
      "category": "ping",
      "timestamp": 1634455930.39
    },
    {
      "data": {
        "tab": {
          "id": 307,
          "favicon": "https://images.immediate.co.uk/production/volatile/sites/4/2019/05/cropped-favicon-bw-f76d239-1e7f748.png?quality=90&resize=32,32"
        }
      },
      "message": "POST https://permutive.sciencefocus.com/v2.0/internal/metrics?k=db07e0f0-8bb8-46c8-b714-291f2768d746",
      "category": "xmlhttprequest",
      "timestamp": 1634455933.441
    },
    {
      "data": {
        "tab": {
          "id": 307,
          "favicon": "https://images.immediate.co.uk/production/volatile/sites/4/2019/05/cropped-favicon-bw-f76d239-1e7f748.png?quality=90&resize=32,32"
        }
      },
      "message": "GET https://cdn.jwplayer.com/strips/7IBnivDg-120.vtt",
      "category": "xmlhttprequest",
      "timestamp": 1634455969.683
    }
  ],
  "environment": "airlock Browser Extension",
  "fingerprint": [
    "www.google.com"
  ]
}