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