Push Security Webhooks (v1)

Download OpenAPI specification:Download

support: support@pushsecurity.com URL: https://pushsecurity.com/contact/ License: Commercial Terms of Service

Overview

Configure webhooks for the Push Security platform and receive real-time updates when events occur.

Each webhook event has the following:

Versioning
Idempotency key
Metadata
New and old objects to show exactly what has changed
A signature for verifying sender authenticity

Acknowledging an event

Your endpoint has 5 seconds to respond with a 200 OK (or any other 2xx response). Otherwise, retry behavior will be triggered.

Retry behavior

Each event will be sent a maximum of 4 times at the following time intervals:

Immediately
After 1 minute
After 5 minutes
After 25 minutes

If the event is acknowledged within a 5-second window, no more retries will be attempted.

Each retry of the event will have a newly generated X-Signature, but the event id will be the same for all retries.

Handling duplicate events

The payload body is JSON-encoded and contains an idempotency key named id. If you want to ensure that you handle an event exactly once, please store this value and compare it against incoming events. This can be used to discard duplicate events that have been delivered more than once.

Verifying signatures

Each event has a header X-Signature which contains 2 parts:

A UNIX timestamp value t (in seconds)
An HMAC-SHA-256 value v1 which contains the payload signature to check using your webhook secret obtained at the time you created it

Here is an example of how it is formatted:

X-Signature: t=1698349494,v1=0E01666E58BC2E6C64E9A5DA66C28CF9D88C3E342CCFC029D56B749A4B4282CE

To calculate and verify the signature, perform the following steps:

Parse the X-Signature header by splitting it first by , and then by = to obtain key-value pairs.
Store the t (timestamp) and v1 (signature) values in variables.
Concatenate the value of t (as a string) with a . and the JSON request body (in its raw format).
Use the HMAC-SHA256 algorithm to compute the hash of the concatenated string.
Compare the computed HMAC with the v1 value from the header to verify the signature.
Additionally, check the timestamp (t) and compare it to the current time. If the difference is bigger than 35 mins (or your preferable threshold) you should discard the event to avoid replay attacks.

Example in Python:

import json
import hmac
import hashlib
import time

# Your secret key for the webhook
SECRET_KEY = b'psws_ad9d0bba8260baf774c3821acaff1b7d'

# Example header and request body (you would normally get these from the incoming HTTP request)
example_header = 't=1698349494,v1=0E01666E58BC2E6C64E9A5DA66C28CF9D88C3E342CCFC029D56B749A4B4282CE'
example_request_body = json.dumps({"key": "value"})

# Step 1: Parse the header
elements = example_header.split(',')
parsed_header = {}
for element in elements:
    key, value = element.split('=')
    parsed_header[key] = value

# Step 2: Store 't' and 'v1' values in variables
received_t = parsed_header.get('t')
received_v1 = parsed_header.get('v1')

# Step 3: Concatenate 't' value with '.' and the JSON request body
payload = f"{received_t}.{example_request_body}"

# Step 4: Compute the HMAC using SHA256
computed_hmac = hmac.new(SECRET_KEY, payload.encode(), hashlib.sha256).hexdigest().upper()

# Step 5: Compare the signature
is_valid = hmac.compare_digest(received_v1, computed_hmac)

# Step 6: Check the timestamp
current_time = int(time.time())
time_difference = current_time - int(received_t)
if time_difference > 2100:  # 35 minutes
    is_valid = False
    message = "Timestamp is too old."
else:
    message = "Signature verified" if is_valid else "Signature mismatch"

print(f"Is the signature valid? {is_valid}. Message: {message}")

Example in Node.js:

const crypto = require('crypto');

// Your secret key for the webhook
const SECRET_KEY = 'psws_ad9d0bba8260baf774c3821acaff1b7d';

// Example header and request body (you'd normally get these from the incoming HTTP request)
const exampleHeader = 't=1698349494,v1=0E01666E58BC2E6C64E9A5DA66C28CF9D88C3E342CCFC029D56B749A4B4282CE';
const exampleRequestBody = JSON.stringify({ key: 'value' });

// Step 1: Parse the header
const elements = exampleHeader.split(',');
const parsedHeader = {};
elements.forEach((element) => {
  const [key, value] = element.split('=');
  parsedHeader[key] = value;
});

// Step 2: Store 't' and 'v1' values in variables
const receivedT = parsedHeader['t'];
const receivedV1 = parsedHeader['v1'];

// Step 3: Concatenate 't' value with '.' and the JSON request body
const payload = `${receivedT}.${exampleRequestBody}`;

// Step 4: Compute the HMAC using SHA256
const computedHmac = crypto.createHmac('sha256', SECRET_KEY).update(payload).digest('hex');

// Step 5: Compare the signature
const isValid = crypto.timingSafeEqual(Buffer.from(receivedV1, 'hex'), Buffer.from(computedHmac, 'hex'));

// Step 6: Check the timestamp
const currentTime = Math.floor(Date.now() / 1000);
const timeDifference = currentTime - parseInt(receivedT, 10);
let message;

if (timeDifference > 2100) {  // 35 minutes
  isValid = false;
  message = 'Timestamp is too old.';
} else {
  message = isValid ? 'Signature verified' : 'Signature mismatch';
}

console.log(`Is the signature valid? ${isValid}. Message: ${message}`);

Versioning

The payload body is JSON-encoded and contains a value named version. You're currently working with version 1 of the Push Security webhooks. Should there be any breaking changes in the future, we'll bump up this version number. If you have any webhooks configured, we'll send you notifications over email about the deprecation date for the older version.

Custom headers

If you need any custom headers configured on your webhook that are required by the receiver, please contact support or reach out to your account representative.

Entities

Events representing CRUD operations on entities.

AccountWebhook

Request

header Parameters

X-Signature

required

string

Example: X-Signature: t=1492774577,v1=5257a869...

Request Body schema: application/json

An account was created, updated or deleted.

version

string

The version of the event.

Example: "1"

string <uuid>

The unique identifier for the event. This can be used as an idempotency key.

Example: "c478966c-f927-411c-b919-179832d3d50c"

timestamp

integer

When the event occurred, formatted as a UNIX timestamp (in seconds).

Example: 1698604061

category

string

The category of the event.

Value: "ENTITY"

description

string

The description of the event. Note: this is subject to change and should not be used to match on this object.

Example: "employee@example.com on Google Workspace updated"

type

string

The type of event that occurred.

Enum: "CREATE" "UPDATE" "DELETE"

object

string

The object that was created, updated or deleted.

Value: "ACCOUNT"

friendlyName

string

The friendly name of this object. Note: this is subject to change and should not be used to match on this object.

Example: "Account"

object (Account)

This object represents an account in your organization.

string

Unique identifier for the account

Example: "d6a32ba5-0532-4a66-8137-48cdf409c972"

employeeId

string

Identifier of primary employee that this account belongs to

Example: "72d0347a-2663-4ef5-b1c5-df39163f1603"

appType

string

The app associated with this account

Example: "ATLASSIAN"

appId

string

The ID of the app associated with this account

Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"

string <email>

The email address used to log into the account

Example: "john.hill@example.com"

mfaRegistered

boolean or null

Whether MFA is registered or not. If unknown, null is provided.

Example: true

mfaMethods

Array of strings or null (MfaMethodsType)

The MFA methods registered for this account

Enum Value	Description
APP_TOTP	Time-based one-time password via app
PUSH_NOTIFICATION	Authentication prompt on device
EMAIL_OTP	One-time password sent to email
U2F	Physical security key
HARDWARE_TOTP	Time-based password via hardware token
PHONE_CALL	Voice verification
SMS_OTP	One-time password sent via SMS
APP_PASSWORD	Specialized password for app access
GRID_CARD	Reference card with codes
EXTERNAL_PROVIDER	Third-party authentication service
BACKUP_CODES	Pre-generated one-time codes
WEBAUTHN	Two-factor authentication with biometrics support

passwordId

string or null

Identifier of the password used on this account. The actual password is not sent up by the browser extension and so this is an identifier for it instead. This value is null if password authentication is not used.

Example: "4c13674f-e88a-4411-bfa2-53a70468a898"

object

passwordLogin	boolean Whether or not this account has been logged into with a password Example: true
oidcLogin	string or null The identity provider that was used to do an OIDC login on this account. This is `null` if no OIDC login has been performed. Example: "GOOGLE_WORKSPACE"
samlLogin	string or null The identity provider that was used to do a SAML login on this account. This is `null` if no SAML login has been performed. Example: "OKTA"
oktaSwaLogin	boolean Whether or not this account has been logged into with Okta SWA Example: true
vendorSsoLogin	string or null Whether or not this account has an associated vendor SSO provider. Example: "GOOGLE_WORKSPACE"

creationTimestamp

integer

When this account was created, formatted as a UNIX timestamp (in seconds)

Example: 1698064423

lastUsedTimestamp

integer or null

When the account was last used by an employee, formatted as a UNIX timestamp (in seconds)

Example: 1698669168

object (Account)

This object represents an account in your organization.

string

Unique identifier for the account

Example: "d6a32ba5-0532-4a66-8137-48cdf409c972"

employeeId

string

Identifier of primary employee that this account belongs to

Example: "72d0347a-2663-4ef5-b1c5-df39163f1603"

appType

string

The app associated with this account

Example: "ATLASSIAN"

appId

string

The ID of the app associated with this account

Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"

string <email>

The email address used to log into the account

Example: "john.hill@example.com"

mfaRegistered

boolean or null

Whether MFA is registered or not. If unknown, null is provided.

Example: true

mfaMethods

Array of strings or null (MfaMethodsType)

The MFA methods registered for this account

Enum Value	Description
APP_TOTP	Time-based one-time password via app
PUSH_NOTIFICATION	Authentication prompt on device
EMAIL_OTP	One-time password sent to email
U2F	Physical security key
HARDWARE_TOTP	Time-based password via hardware token
PHONE_CALL	Voice verification
SMS_OTP	One-time password sent via SMS
APP_PASSWORD	Specialized password for app access
GRID_CARD	Reference card with codes
EXTERNAL_PROVIDER	Third-party authentication service
BACKUP_CODES	Pre-generated one-time codes
WEBAUTHN	Two-factor authentication with biometrics support

passwordId

string or null

Example: "4c13674f-e88a-4411-bfa2-53a70468a898"

object

passwordLogin	boolean Whether or not this account has been logged into with a password Example: true
oidcLogin	string or null The identity provider that was used to do an OIDC login on this account. This is `null` if no OIDC login has been performed. Example: "GOOGLE_WORKSPACE"
samlLogin	string or null The identity provider that was used to do a SAML login on this account. This is `null` if no SAML login has been performed. Example: "OKTA"
oktaSwaLogin	boolean Whether or not this account has been logged into with Okta SWA Example: true
vendorSsoLogin	string or null Whether or not this account has an associated vendor SSO provider. Example: "GOOGLE_WORKSPACE"

creationTimestamp

integer

When this account was created, formatted as a UNIX timestamp (in seconds)

Example: 1698064423

lastUsedTimestamp

integer or null

When the account was last used by an employee, formatted as a UNIX timestamp (in seconds)

Example: 1698669168

Responses

2XX

Return any 2XX status to indicate that the data was received successfully

Account (Other)Webhook

Request

header Parameters

X-Signature

required

string

Example: X-Signature: t=1492774577,v1=5257a869...

Request Body schema: application/json

An account (Other) was created, updated or deleted.

version

string

The version of the event.

Example: "1"

string <uuid>

The unique identifier for the event. This can be used as an idempotency key.

Example: "c478966c-f927-411c-b919-179832d3d50c"

timestamp

integer

When the event occurred, formatted as a UNIX timestamp (in seconds).

Example: 1698604061

type

string

The type of event that occurred.

Enum: "CREATE" "UPDATE" "DELETE"

category

string

The category of the event.

Value: "ENTITY"

description

string

The description of the event. Note: this is subject to change and should not be used to match on this object.

Example: "user@example.com updated on other app (c478966c-f927-411c-b919-179832d3d50c)"

object

string

The object that was created, updated or deleted.

Value: "ACCOUNT_OTHER"

friendlyName

string

The friendly name of this object. Note: this is subject to change and should not be used to match on this object.

Example: "Account (Other)"

object (Account (other))

This object represents an account (other) in your organization.

string

Unique identifier for the account

Example: "1009e8cb-497b-49ae-ac87-e083e42078d2"

employeeId

string

Identifier of primary employee that this account belongs to

Example: "72d0347a-2663-4ef5-b1c5-df39163f1603"

otherAppId

string

The ID of the app associated with this account

Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"

string <email>

The email address used to log into the account

Example: "john.hill@example.com"

object

passwordLogin required	boolean Whether or not this account has been logged into with a password Example: true
oidcLogin required	string or null The identity provider that was used to do an OIDC login on this account. This is `null` if no OIDC login has been performed. Example: "GOOGLE_WORKSPACE"
samlLogin required	string or null The identity provider that was used to do a SAML login on this account. This is `null` if no SAML login has been performed. Example: "OKTA"

creationTimestamp

integer

When the account was first observed, formatted as a UNIX timestamp (in seconds)

Example: 1698064423

lastUsedTimestamp

integer or null

When the account was last used by an employee, formatted as a UNIX timestamp (in seconds)

Example: 1698669168

object (Account (other))

This object represents an account (other) in your organization.

string

Unique identifier for the account

Example: "1009e8cb-497b-49ae-ac87-e083e42078d2"

employeeId

string

Identifier of primary employee that this account belongs to

Example: "72d0347a-2663-4ef5-b1c5-df39163f1603"

otherAppId

string

The ID of the app associated with this account

Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"

string <email>

The email address used to log into the account

Example: "john.hill@example.com"

object

passwordLogin required	boolean Whether or not this account has been logged into with a password Example: true
oidcLogin required	string or null The identity provider that was used to do an OIDC login on this account. This is `null` if no OIDC login has been performed. Example: "GOOGLE_WORKSPACE"
samlLogin required	string or null The identity provider that was used to do a SAML login on this account. This is `null` if no SAML login has been performed. Example: "OKTA"

creationTimestamp

integer

When the account was first observed, formatted as a UNIX timestamp (in seconds)

Example: 1698064423

lastUsedTimestamp

integer or null

When the account was last used by an employee, formatted as a UNIX timestamp (in seconds)

Example: 1698669168

Responses

2XX

Return any 2XX status to indicate that the data was received successfully

AppWebhook

Request

header Parameters

X-Signature

required

string

Example: X-Signature: t=1492774577,v1=5257a869...

Request Body schema: application/json

An app was created, updated or deleted.

version

string

The version of the event.

Example: "1"

string <uuid>

The unique identifier for the event. This can be used as an idempotency key.

Example: "c478966c-f927-411c-b919-179832d3d50c"

timestamp

integer

When the event occurred, formatted as a UNIX timestamp (in seconds).

Example: 1698604061

type

string

The type of event that occurred.

Enum: "CREATE" "UPDATE" "DELETE"

category

string

The category of the event.

Value: "ENTITY"

description

string

The description of the event. Note: this is subject to change and should not be used to match on this object.

Example: "Google Workspace first observed"

object

string

The object that was created, updated or deleted.

Value: "APP"

friendlyName

string

The friendly name of this object. Note: this is subject to change and should not be used to match on this object.

Example: "App"

object (App)

This object represents an app in your organization.

string

Unique identifier for this object

Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"

type

string

The type of app, formatted as an ENUM value.

Example: "ZAPIER"

approvalStatus

string or null (ApprovalStatusType)

Approval status of the app, null if not set

Enum Value	Description
UNDER_REVIEW	The app is under review
APPROVED	The app has been approved
NOT_APPROVED	The app has not been approved

sensitivityLevel

string or null (SensitivityLevelType)

The sensitivity level of the app, null if not set

Enum Value	Description
HIGH	The sensitivity of the app is high
MEDIUM	The sensitivity of the app is medium
LOW	The sensitivity of the app is low

ownerId

string or null

Identifier of the employee who is the owner of this platform

Example: "87569da6-fb7a-4df7-8ce2-246c14044911"

notes

string

Notes recorded on this app (Note - changes to this field do not trigger an UPDATE event)

Example: "Last security audit: 16 January 2023.\n"

creationTimestamp

integer

When the app was first observed, formatted as a UNIX timestamp (in seconds)

Example: 1698064423

object (App)

This object represents an app in your organization.

string

Unique identifier for this object

Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"

type

string

The type of app, formatted as an ENUM value.

Example: "ZAPIER"

approvalStatus

string or null (ApprovalStatusType)

Approval status of the app, null if not set

Enum Value	Description
UNDER_REVIEW	The app is under review
APPROVED	The app has been approved
NOT_APPROVED	The app has not been approved

sensitivityLevel

string or null (SensitivityLevelType)

The sensitivity level of the app, null if not set

Enum Value	Description
HIGH	The sensitivity of the app is high
MEDIUM	The sensitivity of the app is medium
LOW	The sensitivity of the app is low

ownerId

string or null

Identifier of the employee who is the owner of this platform

Example: "87569da6-fb7a-4df7-8ce2-246c14044911"

notes

string

Notes recorded on this app (Note - changes to this field do not trigger an UPDATE event)

Example: "Last security audit: 16 January 2023.\n"

creationTimestamp

integer

When the app was first observed, formatted as a UNIX timestamp (in seconds)

Example: 1698064423

Responses

2XX

Return any 2XX status to indicate that the data was received successfully

App (Other)Webhook

Request

header Parameters

X-Signature

required

string

Example: X-Signature: t=1492774577,v1=5257a869...

Request Body schema: application/json

An app (Other) was created, updated or deleted.

version

string

The version of the event.

Example: "1"

string <uuid>

The unique identifier for the event. This can be used as an idempotency key.

Example: "c478966c-f927-411c-b919-179832d3d50c"

timestamp

integer

When the event occurred, formatted as a UNIX timestamp (in seconds).

Example: 1698604061

type

string

The type of event that occurred.

Enum: "CREATE" "UPDATE" "DELETE"

category

string

The category of the event.

Value: "ENTITY"

description

string

The description of the event. Note: this is subject to change and should not be used to match on this object.

Example: "app.pushsecurity.com first observed"

object

string

The object that was created, updated or deleted.

Value: "APP_OTHER"

friendlyName

string

The friendly name of this object. Note: this is subject to change and should not be used to match on this object.

Example: "App (Other)"

object (App (Other))

This object represents an app (other) in your organization.

id	string Unique identifier for this object Example: "35603905-ff98-4b7d-8940-eb1906a2bdf6"
domain	string or null Domain the user logged into. This value is null if a OIDC login is used Example: "app.pushsecurity.com"
oauthAppId	string or null ID of the oauth app from the Identity Provider. This value is null if a password login is used. Example: "1234567890"
name	string or null Name of the app. This value is null if a password login is used. Example: "Push Security"
hidden	boolean Whether the app is hidden or not.
requestSupportStatus	string Current request support status of the app Example: "DISCOVERED"
creationTimestamp	integer When the app was first observed, formatted as a UNIX timestamp (in seconds) Example: 1698064423

object (App (Other))

This object represents an app (other) in your organization.

id	string Unique identifier for this object Example: "35603905-ff98-4b7d-8940-eb1906a2bdf6"
domain	string or null Domain the user logged into. This value is null if a OIDC login is used Example: "app.pushsecurity.com"
oauthAppId	string or null ID of the oauth app from the Identity Provider. This value is null if a password login is used. Example: "1234567890"
name	string or null Name of the app. This value is null if a password login is used. Example: "Push Security"
hidden	boolean Whether the app is hidden or not.
requestSupportStatus	string Current request support status of the app Example: "DISCOVERED"
creationTimestamp	integer When the app was first observed, formatted as a UNIX timestamp (in seconds) Example: 1698064423

Responses

2XX

Return any 2XX status to indicate that the data was received successfully

BrowserWebhook

Request

header Parameters

X-Signature

required

string

Example: X-Signature: t=1492774577,v1=5257a869...

Request Body schema: application/json

An employee browser was created, updated or deleted.

version

string

The version of the event.

Example: "1"

string <uuid>

The unique identifier for the event. This can be used as an idempotency key.

Example: "c478966c-f927-411c-b919-179832d3d50c"

timestamp

integer

When the event occurred, formatted as a UNIX timestamp (in seconds).

Example: 1698604061

type

string

The type of event that occurred.

Enum: "CREATE" "UPDATE" "DELETE"

category

string

The category of the event.

Value: "ENTITY"

description

string

The description of the event. Note: this is subject to change and should not be used to match on this object.

Example: "New browser for user@example.com"

object

string

The object that was created, updated or deleted.

Value: "BROWSER"

friendlyName

string

The friendly name of this object. Note: this is subject to change and should not be used to match on this object.

Example: "Browser"

object (Browser)

This object represents an employee's browser in your organization.

id	string Unique identifier for the browser Example: "1852b6ab-0cca-4c8d-8f14-4905497504ec"
employeeId	string Unique identifier for the employee Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
email	string <email> Email address of the employee Example: "john.hill@example.com"
version	string Version of the browser Example: "125.0.0.0"
tokenType	string Type of enrollment token used Enum: "INDIVIDUAL" "TEAM"
isActive	boolean Whether the browser extension is used by a licensed employee Example: true
browser	any (BrowserType) The browser used by the employee Enum: "CHROME" "FIREFOX" "EDGE" "SAFARI" "OPERA" "BRAVE" "ARC" "UNKNOWN"
os	any (OSType) The OS used by the employee Enum: "MACOS" "WINDOWS" "LINUX" "CHROME_OS" "IOS" "ANDROID" "UNKNOWN"
extensionVersion	string Version of the Push extension Example: "1.66.17"
creationTimestamp	integer When this browser object was created, formatted as a UNIX timestamp (in seconds) Example: 1698669223
lastOnlineTimestamp	integer When this browser was last seen, formatted as a UNIX timestamp (in seconds) Example: 1716290202

object (Browser)

This object represents an employee's browser in your organization.

id	string Unique identifier for the browser Example: "1852b6ab-0cca-4c8d-8f14-4905497504ec"
employeeId	string Unique identifier for the employee Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
email	string <email> Email address of the employee Example: "john.hill@example.com"
version	string Version of the browser Example: "125.0.0.0"
tokenType	string Type of enrollment token used Enum: "INDIVIDUAL" "TEAM"
isActive	boolean Whether the browser extension is used by a licensed employee Example: true
browser	any (BrowserType) The browser used by the employee Enum: "CHROME" "FIREFOX" "EDGE" "SAFARI" "OPERA" "BRAVE" "ARC" "UNKNOWN"
os	any (OSType) The OS used by the employee Enum: "MACOS" "WINDOWS" "LINUX" "CHROME_OS" "IOS" "ANDROID" "UNKNOWN"
extensionVersion	string Version of the Push extension Example: "1.66.17"
creationTimestamp	integer When this browser object was created, formatted as a UNIX timestamp (in seconds) Example: 1698669223
lastOnlineTimestamp	integer When this browser was last seen, formatted as a UNIX timestamp (in seconds) Example: 1716290202

Responses

2XX

Return any 2XX status to indicate that the data was received successfully

EmployeeWebhook

Request

header Parameters

X-Signature

required

string

Example: X-Signature: t=1492774577,v1=5257a869...

Request Body schema: application/json

An employee was created, updated or deleted.

version

string

The version of the event.

Example: "1"

string <uuid>

The unique identifier for the event. This can be used as an idempotency key.

Example: "c478966c-f927-411c-b919-179832d3d50c"

timestamp

integer

When the event occurred, formatted as a UNIX timestamp (in seconds).

Example: 1698604061

type

string

The type of event that occurred.

Enum: "CREATE" "UPDATE" "DELETE"

category

string

The category of the event.

Value: "ENTITY"

description

string

The description of the event. Note: this is subject to change and should not be used to match on this object.

Example: "employee@example.com added"

object

string

The object that was created, updated or deleted.

Value: "EMPLOYEE"

friendlyName

string

The friendly name of this object. Note: this is subject to change and should not be used to match on this object.

Example: "Employee"

object or null (Employee)

This object represents an employee in your organization.

id	string Unique identifier for the employee Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
email	string <email> Email address of the employee Example: "john.hill@example.com"
firstName	string First name of the employee Note: changes to this field do not trigger an UPDATE event Example: "John"
lastName	string Last name of the employee Note: changes to this field do not trigger an UPDATE event Example: "Hill"
department	string Department - as provided by connected API integrations Note: changes to this field do not trigger an UPDATE event Example: "Security Engineering"
location	string Location - as provided by connected API integrations Note: changes to this field do not trigger an UPDATE event Example: "New York"
licensed	boolean Whether the employee is licensed on the Push platform Example: true
chatopsEnabled	boolean Deprecated Whether the employee has ChatOps enabled Deprecation notice: this value no longer does anything unless you still have access to the legacy Employee chat topics functionality on your account. It will be removed in the next API version. Example: true
creationTimestamp	integer When this employee was created, formatted as a UNIX timestamp (in seconds) Example: 1698669223

object or null (Employee)

This object represents an employee in your organization.

id	string Unique identifier for the employee Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
email	string <email> Email address of the employee Example: "john.hill@example.com"
firstName	string First name of the employee Note: changes to this field do not trigger an UPDATE event Example: "John"
lastName	string Last name of the employee Note: changes to this field do not trigger an UPDATE event Example: "Hill"
department	string Department - as provided by connected API integrations Note: changes to this field do not trigger an UPDATE event Example: "Security Engineering"
location	string Location - as provided by connected API integrations Note: changes to this field do not trigger an UPDATE event Example: "New York"
licensed	boolean Whether the employee is licensed on the Push platform Example: true
chatopsEnabled	boolean Deprecated Whether the employee has ChatOps enabled Deprecation notice: this value no longer does anything unless you still have access to the legacy Employee chat topics functionality on your account. It will be removed in the next API version. Example: true
creationTimestamp	integer When this employee was created, formatted as a UNIX timestamp (in seconds) Example: 1698669223

Responses

2XX

Return any 2XX status to indicate that the data was received successfully

FindingWebhook

Request

header Parameters

X-Signature

required

string

Example: X-Signature: t=1492774577,v1=5257a869...

Request Body schema: application/json

A finding was created, updated or deleted.

version

string

The version of the event.

Example: "1"

string <uuid>

The unique identifier for the event. This can be used as an idempotency key.

Example: "c478966c-f927-411c-b919-179832d3d50c"

timestamp

integer

When the event occurred, formatted as a UNIX timestamp (in seconds).

Example: 1698604061

type

string

The type of event that occurred.

Enum: "CREATE" "UPDATE" "DELETE"

category

string

The category of the event.

Value: "ENTITY"

description

string

The description of the event. Note: this is subject to change and should not be used to match on this object.

Example: "MFA not registered finding observed for user@example.com on Google Workspace"

object

string

The object that was created, updated or deleted.

Value: "FINDING"

friendlyName

string

The friendly name of this object. Note: this is subject to change and should not be used to match on this object.

Example: "Finding"

object (Finding)

This object represents a finding in your organization.

string

Unique identifier for the finding

Example: "d6a32ba5-0532-4a66-8137-48cdf409c972"

type

string (FindingType)

The type of finding

Enum Value	Description
MFA_NOT_REGISTERED	This account does not have MFA.
REUSED_PASSWORD	The password used on the account is being reused.
SHARED_ACCOUNT	The account credentials are being shared with another employee.
UNUSED_THIRD_PARTY_APP	The third-party integration has not been used in 90 days or more.
WEAK_PASSWORD	The password used on the account is weak.
LEAKED_PASSWORD	The password used on the account has been leaked in a data breach.
PASSWORD_MANAGER_NOT_USED	The employee typically uses manually typed passwords, rather than a password manager.
STOLEN_CREDENTIALS	The credentials used on the account have been identified as stolen.

state

string (FindingState)

The state of the finding

Enum Value	Description
OPEN	The finding has been confirmed and is open.
RESOLVED	The finding has been resolved and is no longer an issue.

employeeId

string or null

ID of the employee this finding is linked to, null if finding is not linked to an employee.

Example: "379ac7ea-ff2a-42ef-af37-06d2020dc46a"

passwordId

string or null

ID of the password this finding is linked to, null if finding is not linked to a password.

Example: "c4a045a1-5331-4714-af83-6a361e98960d"

accountId

string or null

ID of the account this finding is linked to, null if finding is not linked to an account.

appType

string or null

The type of app this finding is linked to, null if finding is not linked to an app.

Example: "PUSH_SECURITY"

appId

string or null

ID of the app this finding is linked to, null if finding is not linked to an app.

Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"

creationTimestamp

integer

When this finding was first observed, formatted as a UNIX timestamp (in seconds)

Example: 1698064423

object (Finding)

This object represents a finding in your organization.

string

Unique identifier for the finding

Example: "d6a32ba5-0532-4a66-8137-48cdf409c972"

type

string (FindingType)

The type of finding

Enum Value	Description
MFA_NOT_REGISTERED	This account does not have MFA.
REUSED_PASSWORD	The password used on the account is being reused.
SHARED_ACCOUNT	The account credentials are being shared with another employee.
UNUSED_THIRD_PARTY_APP	The third-party integration has not been used in 90 days or more.
WEAK_PASSWORD	The password used on the account is weak.
LEAKED_PASSWORD	The password used on the account has been leaked in a data breach.
PASSWORD_MANAGER_NOT_USED	The employee typically uses manually typed passwords, rather than a password manager.
STOLEN_CREDENTIALS	The credentials used on the account have been identified as stolen.

state

string (FindingState)

The state of the finding

Enum Value	Description
OPEN	The finding has been confirmed and is open.
RESOLVED	The finding has been resolved and is no longer an issue.

employeeId

string or null

ID of the employee this finding is linked to, null if finding is not linked to an employee.

Example: "379ac7ea-ff2a-42ef-af37-06d2020dc46a"

passwordId

string or null

ID of the password this finding is linked to, null if finding is not linked to a password.

Example: "c4a045a1-5331-4714-af83-6a361e98960d"

accountId

string or null

ID of the account this finding is linked to, null if finding is not linked to an account.

appType

string or null

The type of app this finding is linked to, null if finding is not linked to an app.

Example: "PUSH_SECURITY"

appId

string or null

ID of the app this finding is linked to, null if finding is not linked to an app.

Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"

creationTimestamp

integer

When this finding was first observed, formatted as a UNIX timestamp (in seconds)

Example: 1698064423

Responses

2XX

Return any 2XX status to indicate that the data was received successfully

Activity

Events representing employee activity.

LoginWebhook

Request

header Parameters

X-Signature

required

string

Example: X-Signature: t=1492774577,v1=5257a869...

Request Body schema: application/json

A login occurred.

version

string

The version of the event.

Example: "1"

string <uuid>

The unique identifier for the event. This can be used as an idempotency key.

Example: "c478966c-f927-411c-b919-179832d3d50c"

timestamp

integer

When the event occurred, formatted as a UNIX timestamp (in seconds).

Example: 1698604061

category

string

The category of the event.

Value: "ACTIVITY"

description

string

The description of the event. Note: this is subject to change and should not be used to match on this object.

Example: "user@example.com logged into https://login.com using a password"

object

string

The object that was created.

Value: "LOGIN"

friendlyName

string

The friendly name of this object. Note: this is subject to change and should not be used to match on this object.

Example: "Login"

object (Login)

This object represents a login event, indicating when an employee accesses an application by logging in.

employeeId

string

Identifier of employee who used this account

Example: "72d0347a-2663-4ef5-b1c5-df39163f1603"

accountId

string or null

Identifier for the account that was logged into. This value is null when workApp=false.

Example: "37cda962-7e78-49bc-8721-1becd16276a3"

appType

string or null

The app associated with this account. This value is null when workApp=false.

Example: "ATLASSIAN"

appId

string or null

The identifier of the app associated with this account. This value is null when workApp=false.

Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"

string <email>

The email address used to log into the account

Example: "john.hill@example.com"

loginTimestamp

integer

When the login occurred. Formatted as a UNIX timestamp (in seconds).

Example: 1698064423

loginUrl

string

The URL where the login took place.

Example: "https://www.example.com/login"

workApp

boolean

Whether the app is recognized as a commonly used work app. Learn more.

Example: true

passwordManuallyTyped

boolean or null

Whether the password was manually typed (or a password manager was used). This value is null if password authentication was not used.

Example: true

weakPassword

boolean or null

True if the password used was considered weak. This value is null if password authentication was not used.

Example: true

weakPasswordReasons

Array of strings or null (FindingType)

Reasons a password is weak. This value is null if weakPassword is false or null.

Enum Value	Description
COMPROMISED_HIBP	Password appears in the Have I Been Pwnd database.
COMMON_BASE_WORD	The base word is a derivative of top 10000 most used passwords.
BANNED_BASE_WORD	The password is a derivative of a custom banned word.

leakedPassword

boolean or null

Whether the password used on the account has been leaked in a data breach or not. This value is null if password authentication is not used.

Example: true

loginType

string or null (LoginType)

All possible ENUM values for login types

Enum: "OIDC" "SAML" "USERNAME_PASSWORD"

identityProvider

string or null

The identity provider used to authenticate. This value is null if password authentication was used.

Example: "OKTA"

sourceIpAddress

string

The IP address of the user logging in.

Example: "8.158.25.38"

browser

any (BrowserType)

The browser used by the employee

Enum: "CHROME" "FIREFOX" "EDGE" "SAFARI" "OPERA" "BRAVE" "ARC" "UNKNOWN"

any (OSType)

The OS used by the employee

Enum: "MACOS" "WINDOWS" "LINUX" "CHROME_OS" "IOS" "ANDROID" "UNKNOWN"

userAgent

string

The user agent string reported by the browser

Example: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36 Edge/16.16299"

passwordId

string or null

The identifier of the password used to login. This value is null if password authentication was not used.

Example: "9c816f55-7453-49e5-bc60-6b1b9b38cadc"

Responses

2XX

Return any 2XX status to indicate that the data was received successfully

Controls

Events related to any of the control features.

App bannerWebhook

Request

header Parameters

X-Signature

required

string

Example: X-Signature: t=1492774577,v1=5257a869...

Request Body schema: application/json

An app banner event was detected.

version

string

The version of the event.

Example: "1"

string <uuid>

The unique identifier for the event. This can be used as an idempotency key.

Example: "c478966c-f927-411c-b919-179832d3d50c"

timestamp

integer

When the event occurred, formatted as a UNIX timestamp (in seconds).

Example: 1698604061

category

string

The category of the event.

Value: "CONTROL"

description

string

The description of the event. Note: this is subject to change and should not be used to match on this object.

Example: "user@example.com saw a banner on Google Workspace"

object

string

The object that was created.

Value: "APP_BANNER"

friendlyName

string

The friendly name of this object. Note: this is subject to change and should not be used to match on this object.

Example: "App banner"

object (App banner)

This object represents an app banner event, indicating an employee has interacted with an app banner.

object (Employee)

This object represents an employee in your organization.

id	string Unique identifier for the employee Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
email	string <email> Email address of the employee Example: "john.hill@example.com"
firstName	string First name of the employee Example: "John"
lastName	string Last name of the employee Example: "Hill"
department	string Department - as provided by connected API integrations Example: "Security Engineering"
location	string Location - as provided by connected API integrations Example: "New York"
licensed	boolean Whether the employee is licensed on the Push platform Example: true
chatopsEnabled	boolean Deprecated Whether the employee has ChatOps enabled Deprecation notice: this value no longer does anything unless you still have access to the legacy Employee chat topics functionality on your account. It will be removed in the next API version. Example: true
groups	Array of strings Groups the employee is in Example: ["engineering","marketing"]
creationTimestamp	integer When this employee was created, formatted as a UNIX timestamp (in seconds) Example: 1698669223

appType

string

The app that the banner was configured on.

Example: "OPENAI"

object (App Banner)

This object represents an app banner.

title	string Title of the app banner. Example: "This is a title"
subtext	string Subtext of the app banner. Example: "This is the subtext that supports limited [markdown](https://markdown.org)"
mode	string (AppBannerModeType) All possible ENUM values for app banner modes Enum: "INFORM" "ACKNOWLEDGE" "REASON" "BLOCK"
buttonText	string or null Button text of the app banner. Only applicable when the app banner is in `ACKNOWLEDGE` or `REASON` mode, or is in `BLOCK` mode with `allowReasonSubmission` set to true. Example: "Proceed anyway"
allowReasonSubmission	boolean or null Whether the user is allowed to submit a request to access a blocked page. Only applicable when the app banner is in `BLOCK` mode. Example: false

action

string (AppBannerActionType)

All possible ENUM values for app banner actions

Enum: "ACKNOWLEDGED" "DISPLAYED" "SUBMITTED_REASON"

reason

string or null

Reason provided by the employee for bypassing or requesting access to the app. Applicable when the action is SUBMITTED_REASON.

Example: "I need to access this app for my work."

sourceIpAddress

string

The IP address of the user interacting with the app banner.

Example: "8.158.25.38"

browser

any (BrowserType)

The browser used by the employee

Enum: "CHROME" "FIREFOX" "EDGE" "SAFARI" "OPERA" "BRAVE" "ARC" "UNKNOWN"

any (OSType)

The OS used by the employee

Enum: "MACOS" "WINDOWS" "LINUX" "CHROME_OS" "IOS" "ANDROID" "UNKNOWN"

userAgent

string

The user agent string reported by the browser

Example: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36 Edge/16.16299"

Responses

2XX

Return any 2XX status to indicate that the data was received successfully

Blocked URL visitedWebhook

Request

header Parameters

X-Signature

required

string

Example: X-Signature: t=1492774577,v1=5257a869...

Request Body schema: application/json

A blocked URL was visited.

version

string

The version of the event.

Example: "1"

string <uuid>

The unique identifier for the event. This can be used as an idempotency key.

Example: "c478966c-f927-411c-b919-179832d3d50c"

timestamp

integer

When the event occurred, formatted as a UNIX timestamp (in seconds).

Example: 1698604061

category

string

The category of the event.

Value: "CONTROL"

description

string

The description of the event. Note: this is subject to change and should not be used to match on this object.

Example: "user@example.com attempted to visit https://blocked.com"

object

string

The object that was created.

Value: "BLOCKED_URL_VISITED"

friendlyName

string

The friendly name of this object. Note: this is subject to change and should not be used to match on this object.

Example: "Blocked URL visited"

object (Blocked URL Visited)

This object represents a blocked URL visited event, indicating an employee tried to visit a URL that has been blocked.

object (Employee)

This object represents an employee in your organization.

id	string Unique identifier for the employee Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
email	string <email> Email address of the employee Example: "john.hill@example.com"
firstName	string First name of the employee Example: "John"
lastName	string Last name of the employee Example: "Hill"
department	string Department - as provided by connected API integrations Example: "Security Engineering"
location	string Location - as provided by connected API integrations Example: "New York"
licensed	boolean Whether the employee is licensed on the Push platform Example: true
chatopsEnabled	boolean Deprecated Whether the employee has ChatOps enabled Deprecation notice: this value no longer does anything unless you still have access to the legacy Employee chat topics functionality on your account. It will be removed in the next API version. Example: true
groups	Array of strings Groups the employee is in Example: ["engineering","marketing"]
creationTimestamp	integer When this employee was created, formatted as a UNIX timestamp (in seconds) Example: 1698669223

url

string

The blocked URL.

Example: "https://example.com/login"

referrerUrl

string or null

The URL the user was on before navigating to the blocked URL.

Example: "https://statics.teams.cdn.office.net/"

sourceIpAddress

string

The IP address of the user.

Example: "8.158.25.38"

browser

any (BrowserType)

The browser used by the employee

Enum: "CHROME" "FIREFOX" "EDGE" "SAFARI" "OPERA" "BRAVE" "ARC" "UNKNOWN"

any (OSType)

The OS used by the employee

Enum: "MACOS" "WINDOWS" "LINUX" "CHROME_OS" "IOS" "ANDROID" "UNKNOWN"

userAgent

string

The user agent string reported by the browser.

Example: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36 Edge/16.16299"

Responses

2XX

Return any 2XX status to indicate that the data was received successfully

Cloned login page detectedWebhook

Request

header Parameters

X-Signature

required

string

Example: X-Signature: t=1492774577,v1=5257a869...

Request Body schema: application/json

A cloned login page detected event occurred.

version

string

The version of the event.

Example: "1"

string <uuid>

The unique identifier for the event. This can be used as an idempotency key.

Example: "c478966c-f927-411c-b919-179832d3d50c"

timestamp

integer

When the event occurred, formatted as a UNIX timestamp (in seconds).

Example: 1698604061

category

string

The category of the event.

Value: "CONTROL"

description

string

The description of the event. Note: this is subject to change and should not be used to match on this object.

Example: "john@company.com visited https://evil.com/okta.php which is a clone of a Okta login page"

object

string

The object that was created.

Value: "CLONED_LOGIN_PAGE_DETECTED"

friendlyName

string

The friendly name of this object. Note: this is subject to change and should not be used to match on this object.

Example: "Cloned login page detected"

object (Cloned login page detected)

This object represents a cloned login page detected event.

object (Employee)

This object represents an employee in your organization.

id	string Unique identifier for the employee Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
email	string <email> Email address of the employee Example: "john.hill@example.com"
firstName	string First name of the employee Example: "John"
lastName	string Last name of the employee Example: "Hill"
department	string Department - as provided by connected API integrations Example: "Security Engineering"
location	string Location - as provided by connected API integrations Example: "New York"
licensed	boolean Whether the employee is licensed on the Push platform Example: true
chatopsEnabled	boolean Deprecated Whether the employee has ChatOps enabled Deprecation notice: this value no longer does anything unless you still have access to the legacy Employee chat topics functionality on your account. It will be removed in the next API version. Example: true
groups	Array of strings Groups the employee is in Example: ["engineering","marketing"]
creationTimestamp	integer When this employee was created, formatted as a UNIX timestamp (in seconds) Example: 1698669223

mode

string

Mode that the cloned login page detection control is in.

Enum: "OFF" "MONITOR"

clonedLoginPageType

string

The type of login page that was cloned

Example: "OKTA"

clonedLoginPageUrls

Array of strings

The legitimate login page URL that was cloned.

Example: ["https://login.okta.com"]

url

string

The URL that triggered this detection.

Example: "https://evil.com/okta.php"

referrerUrl

string or null

The URL the user was on before the cloned login page was detected

Example: "https://statics.teams.cdn.office.net/"

sourceIpAddress

string

The IP address of the user.

Example: "8.158.25.38"

browser

any (BrowserType)

The browser used by the employee

Enum: "CHROME" "FIREFOX" "EDGE" "SAFARI" "OPERA" "BRAVE" "ARC" "UNKNOWN"

any (OSType)

The OS used by the employee

Enum: "MACOS" "WINDOWS" "LINUX" "CHROME_OS" "IOS" "ANDROID" "UNKNOWN"

userAgent

string

The user agent string reported by the browser

Example: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36 Edge/16.16299"

Responses

2XX

Return any 2XX status to indicate that the data was received successfully

SSO password usedWebhook

Request

header Parameters

X-Signature

required

string

Example: X-Signature: t=1492774577,v1=5257a869...

Request Body schema: application/json

An SSO password used event occurred.

version

string

The version of the event.

Example: "1"

string <uuid>

The unique identifier for the event. This can be used as an idempotency key.

Example: "c478966c-f927-411c-b919-179832d3d50c"

timestamp

integer

When the event occurred, formatted as a UNIX timestamp (in seconds).

Example: 1698604061

category

string

The category of the event.

Value: "CONTROL"

description

string

The description of the event. Note: this is subject to change and should not be used to match on this object.

Example: "user@example.com ignored warning page"

object

string

The object that was created.

Value: "SSO_PASSWORD_USED"

friendlyName

string

The friendly name of this object. Note: this is subject to change and should not be used to match on this object.

Example: "SSO password used"

object (SSO Password used)

This object represents an SSO password used event, indicating when an employee has typed a known IdP password into an unknown domain.

object (Employee)

This object represents an employee in your organization.

id	string Unique identifier for the employee Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
email	string <email> Email address of the employee Example: "john.hill@example.com"
firstName	string First name of the employee Example: "John"
lastName	string Last name of the employee Example: "Hill"
department	string Department - as provided by connected API integrations Example: "Security Engineering"
location	string Location - as provided by connected API integrations Example: "New York"
licensed	boolean Whether the employee is licensed on the Push platform Example: true
chatopsEnabled	boolean Deprecated Whether the employee has ChatOps enabled Deprecation notice: this value no longer does anything unless you still have access to the legacy Employee chat topics functionality on your account. It will be removed in the next API version. Example: true
groups	Array of strings Groups the employee is in Example: ["engineering","marketing"]
creationTimestamp	integer When this employee was created, formatted as a UNIX timestamp (in seconds) Example: 1698669223

mode

any (SsoPasswordProtectionModeType)

The mode that SSO password protection is in.

Enum: "BLOCK" "MONITOR" "WARN" "OFF"

action

any (SsoPasswordProtectionActionType)

The action that the user took while on the SSO password protection page.

Enum: "DISPLAYED" "IGNORED"

url

string

The URL the user entered the password into

Example: "https://evil.com/okta.php"

referrerUrl

string or null

The URL the user was on before entering the password

Example: "https://statics.teams.cdn.office.net/"

string <email>

The email address used to log into the account

Example: "john.hill@example.com"

appType

string

The IdP password that was entered

Example: "OKTA"

sourceIpAddress

string

The IP address of the user logging in.

Example: "8.158.25.38"

browser

any (BrowserType)

The browser used by the employee

Enum: "CHROME" "FIREFOX" "EDGE" "SAFARI" "OPERA" "BRAVE" "ARC" "UNKNOWN"

any (OSType)

The OS used by the employee

Enum: "MACOS" "WINDOWS" "LINUX" "CHROME_OS" "IOS" "ANDROID" "UNKNOWN"

userAgent

string

The user agent string reported by the browser

Example: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36 Edge/16.16299"

Responses

2XX

Return any 2XX status to indicate that the data was received successfully

Phishing tool detectedWebhook

Request

header Parameters

X-Signature

required

string

Example: X-Signature: t=1492774577,v1=5257a869...

Request Body schema: application/json

A phishing tool detected event occurred.

version

string

The version of the event.

Example: "1"

string <uuid>

The unique identifier for the event. This can be used as an idempotency key.

Example: "c478966c-f927-411c-b919-179832d3d50c"

timestamp

integer

When the event occurred, formatted as a UNIX timestamp (in seconds).

Example: 1698604061

category

string

The category of the event.

Value: "CONTROL"

description

string

The description of the event. Note: this is subject to change and should not be used to match on this object.

Example: "user@example.com visited https://phishing.com"

object

string

The object that was created.

Value: "PHISHING_TOOL_DETECTED"

friendlyName

string

The friendly name of this object. Note: this is subject to change and should not be used to match on this object.

Example: "Phishing tool detected"

object (Phishing tool detected)

This object represents a phishing tool detected event.

object (Employee)

This object represents an employee in your organization.

id	string Unique identifier for the employee Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
email	string <email> Email address of the employee Example: "john.hill@example.com"
firstName	string First name of the employee Example: "John"
lastName	string Last name of the employee Example: "Hill"
department	string Department - as provided by connected API integrations Example: "Security Engineering"
location	string Location - as provided by connected API integrations Example: "New York"
licensed	boolean Whether the employee is licensed on the Push platform Example: true
chatopsEnabled	boolean Deprecated Whether the employee has ChatOps enabled Deprecation notice: this value no longer does anything unless you still have access to the legacy Employee chat topics functionality on your account. It will be removed in the next API version. Example: true
groups	Array of strings Groups the employee is in Example: ["engineering","marketing"]
creationTimestamp	integer When this employee was created, formatted as a UNIX timestamp (in seconds) Example: 1698669223

indicator

any (PhishingToolDetectedIndicatorType)

The indicator of the phishing tool that was detected.

Enum: "BITM_TOOL_NOVNC_01" "BITM_TOOL_NOVNC_02" "BITM_TOOL_NOVNC_03" "AITM_TOOL_EVILGINX_01" "AITM_TOOL_EVILGINX_02" "AITM_TOOL_EVILGINX_03" "AITM_TOOL_MODLISHKA_01" "AITM_TOOL_MODLISHKA_02" "AITM_TOOL_MURAENA_01" "AITM_TOOL_MURAENA_02"

url

string

The URL the phishing tool was detected on

Example: "https://evil.com/okta.php"

referrerUrl

string or null

The URL the user was on before the phishing tool was detected

Example: "https://statics.teams.cdn.office.net/"

sourceIpAddress

string

The IP address of the user.

Example: "8.158.25.38"

browser

any (BrowserType)

The browser used by the employee

Enum: "CHROME" "FIREFOX" "EDGE" "SAFARI" "OPERA" "BRAVE" "ARC" "UNKNOWN"

any (OSType)

The OS used by the employee

Enum: "MACOS" "WINDOWS" "LINUX" "CHROME_OS" "IOS" "ANDROID" "UNKNOWN"

userAgent

string

The user agent string reported by the browser

Example: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36 Edge/16.16299"

mode

string or null

Mode that the phishing tool detection control is in.

Enum: "OFF" "MONITOR" "WARN" "BLOCK"

action

string or null

The action that the user took while on the phishing tool detection page.

Enum: "DISPLAYED" "IGNORED"

Responses

2XX

Return any 2XX status to indicate that the data was received successfully

Audit

Audit log events.

Account login method removedWebhook

A login method for an account has been removed

Request

header Parameters

X-Signature

required

string

Example: X-Signature: t=1492774577,v1=5257a869...

Request Body schema: application/json

version

required

string

The version of the event.

Example: "1"

required

string <uuid>

The unique identifier for the event. This can be used as an idempotency key.

Example: "c478966c-f927-411c-b919-179832d3d50c"

timestamp

required

integer

When the event occurred, formatted as a UNIX timestamp (in seconds).

Example: 1698604061

category

required

string

The category of the event.

Value: "AUDIT"

object

required

string

The object that was created.

Value: "ACCOUNT_LOGIN_METHOD_REMOVED"

required

Admin Audit Log Actor (object) or Admin Audit Log Actor API (object)

One of:

This object contains information about the user that performed the action triggering the audit log.

source required	string The source of the action that generated the event. Value: "UI"
email required	string The email address of the actor.
sourceIpAddress required	string The IP address of the actor.
userAgent	string The user agent of the actor, if available.

required

object

accountId required	string The ID of the account. Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
accountEmail required	string The email address associated with the account. Example: "employee@example.com"
appType required	string The name of the app. Example: "ATLASSIAN"
loginMethod required	string The login method removed from the account. Enum: "USERNAME_PASSWORD" "OKTA_SWA" "OIDC" "SAML" Example: "OIDC"

description

string

The description of the event. Note: this is subject to change and should not be used to match on this object.

Example: "user@example.com removed a login method for an account"

friendlyName

string

The friendly name of this object. Note: this is subject to change and should not be used to match on this object.

Example: "Account login method removed"

Responses

2XX

Return any 2XX status to indicate that the data was received successfully

Admin accepted invitationWebhook

A new admin user has accepted the invitation.

Request

header Parameters

X-Signature

required

string

Example: X-Signature: t=1492774577,v1=5257a869...

Request Body schema: application/json

version

required

string

The version of the event.

Example: "1"

required

string <uuid>

The unique identifier for the event. This can be used as an idempotency key.

Example: "c478966c-f927-411c-b919-179832d3d50c"

timestamp

required

integer

When the event occurred, formatted as a UNIX timestamp (in seconds).

Example: 1698604061

category

required

string

The category of the event.

Value: "AUDIT"

object

required

string

The object that was created.

Value: "ADMIN_ACCEPTED_INVITATION"

required

object (Admin Audit Log Actor)

This object contains information about the user that performed the action triggering the audit log.

source required	string The source of the action that generated the event. Value: "UI"
email required	string The email address of the actor.
sourceIpAddress required	string The IP address of the actor.
userAgent	string The user agent of the actor, if available.

required

object

inviter

string

The email address of the admin that sent the invitation.

description

string

The description of the event. Note: this is subject to change and should not be used to match on this object.

Example: "user@example.com joined your team"

friendlyName

string

The friendly name of this object. Note: this is subject to change and should not be used to match on this object.

Example: "Admin accepted invitation"

Responses

2XX

Return any 2XX status to indicate that the data was received successfully

Admin enabled MFAWebhook

An admin user has enabled MFA for their account.

Request

header Parameters

X-Signature

required

string

Example: X-Signature: t=1492774577,v1=5257a869...

Request Body schema: application/json

version

required

string

The version of the event.

Example: "1"

required

string <uuid>

The unique identifier for the event. This can be used as an idempotency key.

Example: "c478966c-f927-411c-b919-179832d3d50c"

timestamp

required

integer

When the event occurred, formatted as a UNIX timestamp (in seconds).

Example: 1698604061

category

required

string

The category of the event.

Value: "AUDIT"

object

required

string

The object that was created.

Value: "ADMIN_ENABLED_MFA"

required

object (Admin Audit Log Actor)

This object contains information about the user that performed the action triggering the audit log.

source required	string The source of the action that generated the event. Value: "UI"
email required	string The email address of the actor.
sourceIpAddress required	string The IP address of the actor.
userAgent	string The user agent of the actor, if available.

required

object

method

required

string

The MFA method used.

Value: "APP_TOTP"

description

string

The description of the event. Note: this is subject to change and should not be used to match on this object.

Example: "user@example.com enabled MFA on their Push account"

friendlyName

string

The friendly name of this object. Note: this is subject to change and should not be used to match on this object.

Example: "Admin enabled MFA"

Responses

2XX

Return any 2XX status to indicate that the data was received successfully

Admin logged inWebhook

An admin user has logged in.

Request

header Parameters

X-Signature

required

string

Example: X-Signature: t=1492774577,v1=5257a869...

Request Body schema: application/json

version

required

string

The version of the event.

Example: "1"

required

string <uuid>

The unique identifier for the event. This can be used as an idempotency key.

Example: "c478966c-f927-411c-b919-179832d3d50c"

timestamp

required

integer

When the event occurred, formatted as a UNIX timestamp (in seconds).

Example: 1698604061

category

required

string

The category of the event.

Value: "AUDIT"

object

required

string

The object that was created.

Value: "ADMIN_LOGGED_IN"

required

object (Admin Audit Log Actor)

This object contains information about the user that performed the action triggering the audit log.

source required	string The source of the action that generated the event. Value: "UI"
email required	string The email address of the actor.
sourceIpAddress required	string The IP address of the actor.
userAgent	string The user agent of the actor, if available.

description

string

The description of the event. Note: this is subject to change and should not be used to match on this object.

Example: "user@example.com logged into the Push platform"

friendlyName

string

The friendly name of this object. Note: this is subject to change and should not be used to match on this object.

Example: "Admin logged in"

Responses

2XX

Return any 2XX status to indicate that the data was received successfully

Admin removedWebhook

An admin user has been removed.

Request

header Parameters

X-Signature

required

string

Example: X-Signature: t=1492774577,v1=5257a869...

Request Body schema: application/json

version

required

string

The version of the event.

Example: "1"

required

string <uuid>

The unique identifier for the event. This can be used as an idempotency key.

Example: "c478966c-f927-411c-b919-179832d3d50c"

timestamp

required

integer

When the event occurred, formatted as a UNIX timestamp (in seconds).

Example: 1698604061

category

required

string

The category of the event.

Value: "AUDIT"

object

required

string

The object that was created.

Value: "ADMIN_REMOVED"

required

object (Admin Audit Log Actor)

This object contains information about the user that performed the action triggering the audit log.

source required	string The source of the action that generated the event. Value: "UI"
email required	string The email address of the actor.
sourceIpAddress required	string The IP address of the actor.
userAgent	string The user agent of the actor, if available.

required

object

target

required

string

The email address of the removed admin user.

description

string

The description of the event. Note: this is subject to change and should not be used to match on this object.

Example: "user@example.com removed another.user@example.com from your team"

friendlyName

string

The friendly name of this object. Note: this is subject to change and should not be used to match on this object.

Example: "Admin removed"

Responses

2XX

Return any 2XX status to indicate that the data was received successfully

API key addedWebhook

An admin user has added a new API Key.

Request

header Parameters

X-Signature

required

string

Example: X-Signature: t=1492774577,v1=5257a869...

Request Body schema: application/json

version

required

string

The version of the event.

Example: "1"

required

string <uuid>

The unique identifier for the event. This can be used as an idempotency key.

Example: "c478966c-f927-411c-b919-179832d3d50c"

timestamp

required

integer

When the event occurred, formatted as a UNIX timestamp (in seconds).

Example: 1698604061

category

required

string

The category of the event.

Value: "AUDIT"

object

required

string

The object that was created.

Value: "API_KEY_ADDED"

required

object (Admin Audit Log Actor)

This object contains information about the user that performed the action triggering the audit log.

source required	string The source of the action that generated the event. Value: "UI"
email required	string The email address of the actor.
sourceIpAddress required	string The IP address of the actor.
userAgent	string The user agent of the actor, if available.

required

object

permissions

required

string

The permissions granted to the API key.

Enum Value	Description
FULL_ACCESS	Allows all request types to all endpoints in the API
READ_ONLY	Allows only GET requests to the API

name

string

A friendly name for the API Key, if one is chosen.

Example: "CI/CD access"

description

string

The description of the event. Note: this is subject to change and should not be used to match on this object.

Example: "user@example.com configured a new API Key"

friendlyName

string

The friendly name of this object. Note: this is subject to change and should not be used to match on this object.

Example: "API key added"

Responses

2XX

Return any 2XX status to indicate that the data was received successfully

API key removedWebhook

An admin user has removed an API Key.

Request

header Parameters

X-Signature

required

string

Example: X-Signature: t=1492774577,v1=5257a869...

Request Body schema: application/json

version

required

string

The version of the event.

Example: "1"

required

string <uuid>

The unique identifier for the event. This can be used as an idempotency key.

Example: "c478966c-f927-411c-b919-179832d3d50c"

timestamp

required

integer

When the event occurred, formatted as a UNIX timestamp (in seconds).

Example: 1698604061

category

required

string

The category of the event.

Value: "AUDIT"

object

required

string

The object that was created.

Value: "API_KEY_REMOVED"

required

object (Admin Audit Log Actor)

This object contains information about the user that performed the action triggering the audit log.

source required	string The source of the action that generated the event. Value: "UI"
email required	string The email address of the actor.
sourceIpAddress required	string The IP address of the actor.
userAgent	string The user agent of the actor, if available.

required

object

name	string A friendly name for the API Key, if one is chosen. Example: "CI/CD access"

description

string

The description of the event. Note: this is subject to change and should not be used to match on this object.

Example: "user@example.com removed an existing API Key"

friendlyName

string

The friendly name of this object. Note: this is subject to change and should not be used to match on this object.

Example: "API key removed"

Responses

2XX

Return any 2XX status to indicate that the data was received successfully

App approval status updatedWebhook

The approval status of an app has been updated

Request

header Parameters

X-Signature

required

string

Example: X-Signature: t=1492774577,v1=5257a869...

Request Body schema: application/json

version

required

string

The version of the event.

Example: "1"

required

string <uuid>

The unique identifier for the event. This can be used as an idempotency key.

Example: "c478966c-f927-411c-b919-179832d3d50c"

timestamp

required

integer

When the event occurred, formatted as a UNIX timestamp (in seconds).

Example: 1698604061

category

required

string

The category of the event.

Value: "AUDIT"

object

required

string

The object that was created.

Value: "APP_APPROVAL_STATUS_UPDATED"

required

Admin Audit Log Actor (object) or Admin Audit Log Actor API (object)

One of:

This object contains information about the user that performed the action triggering the audit log.

source required	string The source of the action that generated the event. Value: "UI"
email required	string The email address of the actor.
sourceIpAddress required	string The IP address of the actor.
userAgent	string The user agent of the actor, if available.

required

object

appId required	string The ID of the app. Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
appType required	string The name of the app. Example: "ATLASSIAN"
approvalStatus required	string or null The approval status of the app after the update.

description

string

The description of the event. Note: this is subject to change and should not be used to match on this object.

Example: "user@example.com updated the app approval status"

friendlyName

string

The friendly name of this object. Note: this is subject to change and should not be used to match on this object.

Example: "App approval status updated"

Responses

2XX

Return any 2XX status to indicate that the data was received successfully

App banner configuredWebhook

An app banner was configured.

Request

header Parameters

X-Signature

required

string

Example: X-Signature: t=1492774577,v1=5257a869...

Request Body schema: application/json

version

required

string

The version of the event.

Example: "1"

required

string <uuid>

The unique identifier for the event. This can be used as an idempotency key.

Example: "c478966c-f927-411c-b919-179832d3d50c"

timestamp

required

integer

When the event occurred, formatted as a UNIX timestamp (in seconds).

Example: 1698604061

category

required

string

The category of the event.

Value: "AUDIT"

object

required

string

The object that was created.

Value: "APP_BANNER_CONFIGURED"

required

Admin Audit Log Actor (object) or Admin Audit Log Actor API (object)

One of:

This object contains information about the user that performed the action triggering the audit log.

source required	string The source of the action that generated the event. Value: "UI"
email required	string The email address of the actor.
sourceIpAddress required	string The IP address of the actor.
userAgent	string The user agent of the actor, if available.

required

object

title required	string Title of the app banner. Example: "This is a title"
subtext required	string Subtext of the app banner. Example: "This is the subtext that supports limited [markdown](https://markdown.org)"
mode required	string (AppBannerModeType) All possible ENUM values for app banner modes Enum: "INFORM" "ACKNOWLEDGE" "REASON" "BLOCK"
buttonText	string or null Button text of the app banner. Only applicable when the app banner is in `ACKNOWLEDGE` or `REASON` mode, or is in `BLOCK` mode with `allowReasonSubmission` set to true. Example: "Proceed anyway"
allowReasonSubmission	boolean or null Whether the user is allowed to submit a request to access a blocked page. Only applicable when the app banner is in `BLOCK` mode. Example: false

description

string

The description of the event. Note: this is subject to change and should not be used to match on this object.

Example: "user@example assigned licenses to employees"

friendlyName

string

The friendly name of this object. Note: this is subject to change and should not be used to match on this object.

Example: "License assigned"

Responses

2XX

Return any 2XX status to indicate that the data was received successfully

App banner enabledWebhook

An app banner was enabled or disabled.

Request

header Parameters

X-Signature

required

string

Example: X-Signature: t=1492774577,v1=5257a869...

Request Body schema: application/json

version

required

string

The version of the event.

Example: "1"

required

string <uuid>

The unique identifier for the event. This can be used as an idempotency key.

Example: "c478966c-f927-411c-b919-179832d3d50c"

timestamp

required

integer

When the event occurred, formatted as a UNIX timestamp (in seconds).

Example: 1698604061

category

required

string

The category of the event.

Value: "AUDIT"

object

required

string

The object that was created.

Value: "APP_BANNER_CONFIGURED"

required

Admin Audit Log Actor (object) or Admin Audit Log Actor API (object)

One of:

This object contains information about the user that performed the action triggering the audit log.

source required	string The source of the action that generated the event. Value: "UI"
email required	string The email address of the actor.
sourceIpAddress required	string The IP address of the actor.
userAgent	string The user agent of the actor, if available.

required

object

enabled

required

boolean

Whether the app banner is enabled or disabled.

Example: true

description

string

The description of the event. Note: this is subject to change and should not be used to match on this object.

Example: "user@example assigned licenses to employees"

friendlyName

string

The friendly name of this object. Note: this is subject to change and should not be used to match on this object.

Example: "License assigned"

Responses

2XX

Return any 2XX status to indicate that the data was received successfully

App labels addedWebhook

A set of labels has been added to one or more apps.

Request

header Parameters

X-Signature

required

string

Example: X-Signature: t=1492774577,v1=5257a869...

Request Body schema: application/json

version required	string The version of the event. Example: "1"
id required	string <uuid> The unique identifier for the event. This can be used as an idempotency key. Example: "c478966c-f927-411c-b919-179832d3d50c"
timestamp required	integer When the event occurred, formatted as a UNIX timestamp (in seconds). Example: 1698604061
category required	string The category of the event. Value: "AUDIT"