createSiteWebhook
Webhook defines a webhook, modeled after github\u2019s model.
There is two types of webhooks:
Webhooks
Webhooks can be configured at the org level (subset of topics only) and at the site level. It is possible to have multiple topics in the same webhook configuration and/or to have multiple webhooks configured at the same time.
Client Raw Data Webhooks
Raw data webhooks are a special subset of webhooks that provide insight into raw data packets emitted by a client, identified by their advertising MAC address (assets, discovered BLE, connected Wi-Fi, unconnected Wi-Fi). The data that client raw data webhooks encompasses are reporting AP information, RSSI Data, and any special packets/telemetry packets that the client may emit. Note that client raw webhooks are the raw data coming from the client and do not contain the X,Y location data of the client. In order to get the location data for a client please see our location webhooks. Clients can be identified uniquely across these client raw data topics and location webhook topic using MAC address as the Unique identifier (client identifier).
Client Raw Data Webhooks Topics
Topics that correspond to client raw data for different client types.
asset-raw-rssi- Raw data from packets emitted by named and filtered assetsdiscovered-raw-rssi- Raw data from packets emitted by passive BLE deviceswifi-conn-raw- Raw data from packets emitted by connected deviceswifi-unconn-raw- Raw data from packets emitted by unconnected devices (passive)
Asset Filtering for Client Raw Data Webhooks
The asset-raw-rssi webhook topic supports filtering of raw data by incorporating asset filters in the webhook payload.
The filter topic allows multiple Webhooks to receive a subset of the aasset-raw-rssi data by assigning asset filters to a given webhook. The asset-raw-rssi filter topic is filtered-asset-rssi.
A webhook assigned to a filter topic can take a list of AssetFilter IDs, which act as inclusive filters to determine which named asset and filtered asset data is sent to the assigned filter topic. Filters can be applied to multiple webhooks, and the same data can be sent to multiple filter topics.
Rules for Configuring Client Raw Data Webhooks
- Only four instances of a webhook object can contain a specific filter topic. - A site-level entry will override an org-level entry for the same client raw data webhook topic.
- An assigned asset filter must exist and belong to the same site as the webhook it is assigned to.
Preferred authentication method for automation and integrations. Send the API token in the HTTP Authorization header.
Format:
Authorization: Token {apitoken}
Notes:
- An API token generated for a specific admin has the same privileges as that admin
- An API token is automatically removed if it is not used for more than 90 days
- SSO admins cannot generate admin API tokens. Use organization API tokens when scoped Org/Site privileges are needed.
In: header
Path Parameters
uuidRequest Body
application/json
Request Body
Webhook configuration for delivering selected Mist events to an external destination
Asset filter identifiers used to restrict asset-raw-rssi webhook events
Default action applied when none of the rules match the incoming event. enum: permit, block.
"permit"Value in
- "permit"
- "block"
Whether webhook is enabled
trueIf type=http-post, additional custom HTTP headers to add. The headers name and value must be string, total bytes of headers name and value must be less than 1000
Display name of the webhook
Required when oauth2_grant_type==client_credentials; OAuth2 client identifier used to request an access token
Required when oauth2_grant_type==client_credentials; OAuth2 client secret used to request an access token
passwordOAuth2 grant type used when type==oauth2. enum: client_credentials, password.
Value in
- "client_credentials"
- "password"
Required when oauth2_grant_type==password; password used for the OAuth2 token request
passwordOAuth2 scopes included in the token request when type==oauth2
Required when type==oauth2; token endpoint URL used to obtain the OAuth2 access token
Required when oauth2_grant_type==password; username used for the OAuth2 token request
Optional filtering rules to override topics. Each rule permits or blocks events for a topic, optionally based on event payload matching criteria
Only if type=http-post
when secret is provided, two HTTP headers will be added:
- X-Mist-Signature-v2: HMAC_SHA256(secret, body)
- X-Mist-Signature: HMAC_SHA1(secret, body)
Some solutions may not be able to parse multiple events from a single message (e.g. IBM Qradar, DSM). When set to true, only a single event will be sent per message. this feature is only available on certain topics (see List Webhook Topics)
falseRequired if type=splunk. If splunk_token is not defined for a type Splunk webhook, it will not send, regardless if the webhook receiver is configured to accept it.
Event topics delivered by this webhook
Delivery mechanism used by this webhook. enum: aws-sns, google-pubsub, http-post, oauth2, splunk.
"http-post"Value in
- "aws-sns"
- "google-pubsub"
- "http-post"
- "oauth2"
- "splunk"
Destination URL that receives webhook deliveries
When url uses HTTPS, whether to verify the certificate
trueResponse Body
curl -X POST "https://example.com/api/v1/sites/000000ab-00ab-00ab-00ab-0000000000ab/webhooks" \ -H "Content-Type: application/json" \ -d '{ "enabled": true, "headers": {}, "name": "string", "secret": "string", "splunk_token": "string", "topics": [ "location" ], "type": "http-post", "url": "string", "verify_cert": true }'{ "created_time": 0, "enabled": true, "headers": {}, "id": "b069b358-4c97-5319-1f8c-7c5ca64d6ab1", "modified_time": 0, "name": "string", "org_id": "b069b358-4c97-5319-1f8c-7c5ca64d6ab1", "secret": "string", "site_id": "b069b358-4c97-5319-1f8c-7c5ca64d6ab1", "splunk_token": "string", "topics": [ "location" ], "type": "http-post", "url": "string", "verify_cert": true}