Push Security Webhooks (v1)

Download OpenAPI specification:Download

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:

  1. Parse the X-Signature header by splitting it first by , and then by = to obtain key-value pairs.
  2. Store the t (timestamp) and v1 (signature) values in variables.
  3. Concatenate the value of t (as a string) with a . and the JSON request body (in its raw format).
  4. Use the HMAC-SHA256 algorithm to compute the hash of the concatenated string.
  5. Compare the computed HMAC with the v1 value from the header to verify the signature.
  6. 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.

Entities

Events representing CRUD operations on entities.

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"
id
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

Whether the employee has ChatOps enabled

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

Whether the employee has ChatOps enabled

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

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"
id
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.

id
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"
email
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.

id
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"
email
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
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"
id
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.

id
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.

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.

id
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.

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

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"
id
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.

id
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.

id
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

Accounts (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"
id
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.

id
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"
email
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.

id
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"
email
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

Apps (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"
id
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"
id
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" "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" "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

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"
id
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"
email
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" "UNKNOWN"
os
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.

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"
id
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

Whether the employee has ChatOps enabled

Example: true
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/"
email
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" "UNKNOWN"
os
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

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"
id
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 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

Whether the employee has ChatOps enabled

Example: true
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"
buttonText
string or null

Button text of the app banner. Only applicable when the app banner is in ACKNOWLEDGE or REASON mode.

Example: "Proceed anyway"
action
string (AppBannerActionType)

All possible ENUM values for app banner actions

Enum: "ACKNOWLEDGED" "DISPLAYED" "SUBMITTED_REASON"
reason
string or null

Reason why the employee has continued to use the app. Only applicable when the action is 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" "UNKNOWN"
os
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"
id
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

Whether the employee has ChatOps enabled

Example: true
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: "BITB_TOOL_NOVNC_01" "BITB_TOOL_NOVNC_02" "BITB_TOOL_NOVNC_03" "AITM_TOOL_EVILGINX_01" "AITM_TOOL_EVILGINX_02" "AITM_TOOL_EVILGINX_03"
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" "UNKNOWN"
os
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"
id
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

Whether the employee has ChatOps enabled

Example: true
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" "UNKNOWN"
os
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