Download OpenAPI specification:Download
Configure webhooks for the Push Security platform and receive real-time updates when events occur.
Each webhook event has the following:
Your endpoint has 5 seconds to respond with a 200 OK (or any other 2xx response). Otherwise, retry behavior will be triggered.
Each event will be sent a maximum of 4 times at the following time intervals:
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.
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.
Each event has a header X-Signature which contains 2 parts:
t (in seconds)v1 which contains the payload signature to check using your webhook secret obtained at the time you created itHere is an example of how it is formatted:
X-Signature: t=1698349494,v1=0E01666E58BC2E6C64E9A5DA66C28CF9D88C3E342CCFC029D56B749A4B4282CE
To calculate and verify the signature, perform the following steps:
X-Signature header by splitting it first by , and then by = to obtain key-value pairs.t (timestamp) and v1 (signature) values in variables.t (as a string) with a . and the JSON request body (in its raw format).v1 value from the header to verify the signature.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}`);
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.
An employee was created, updated or deleted.
Return any 2XX status to indicate that the data was received successfully
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 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| type | string The type of event that occurred. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| object | string The object that was created, updated or deleted. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Account) This object represents an account in your organization. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object (Account) This object represents an account in your organization. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Return any 2XX status to indicate that the data was received successfully
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. | ||||||||||||||||||||||||||||||||||||||||
| object | string The object that was created, updated or deleted. | ||||||||||||||||||||||||||||||||||||||||
object (Finding) This object represents a finding in your organization. | |||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||
object (Finding) This object represents a finding in your organization. | |||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||
Return any 2XX status to indicate that the data was received successfully
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. | ||||||||||||||||||||||||||||||
| object | string The object that was created, updated or deleted. | ||||||||||||||||||||||||||||||
object (App) This object represents an app in your organization. | |||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||
object (App) This object represents an app in your organization. | |||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||
Return any 2XX status to indicate that the data was received successfully
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. | ||||||||||||||||||||||
| object | string The object that was created, updated or deleted. | ||||||||||||||||||||||
object (Account (other)) This object represents an account (other) in your organization. | |||||||||||||||||||||||
| |||||||||||||||||||||||
object (Account (other)) This object represents an account (other) in your organization. | |||||||||||||||||||||||
| |||||||||||||||||||||||
Return any 2XX status to indicate that the data was received successfully
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. | ||||||||||||||
| object | string The object that was created, updated or deleted. | ||||||||||||||
object (App (Other)) This object represents an app (other) in your organization. | |||||||||||||||
| |||||||||||||||
object (App (Other)) This object represents an app (other) in your organization. | |||||||||||||||
| |||||||||||||||
Return any 2XX status to indicate that the data was received successfully
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 | ||||||||||||||||||||||||||||||||||||||||||||||
| object | string The object that was created. | ||||||||||||||||||||||||||||||||||||||||||||||
object (Login) This object represents a login event, indicating when an employee accesses an application by logging in. | |||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||
Return any 2XX status to indicate that the data was received successfully
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 | ||||||||||||||||||||||||||||||||||||||||||
| object | string The object that was created. | ||||||||||||||||||||||||||||||||||||||||||
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. | |||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||
Return any 2XX status to indicate that the data was received successfully
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 | ||||||||||||||||||||||||||||||||||||
| object | string The object that was created. | ||||||||||||||||||||||||||||||||||||
object (Phishing tool detected) This object represents a phishing tool detected event. | |||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||
Return any 2XX status to indicate that the data was received successfully
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 | ||||||||||||||||||||||||||||||||||
| object | string The object that was created. | ||||||||||||||||||||||||||||||||||
object (Blocked URL Visited) This object represents a blocked URL visited event, indicating an employee tried to visit a URL that has been blocked. | |||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||
Return any 2XX status to indicate that the data was received successfully