Skip to content
/
Phishing tool detection i...

Push Security Webhooks (v1)

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

Creating webhooks

To create or manage your webhooks, go to the Settings page in the Push admin console.

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

Custom headers

Some SIEMs or other external systems where you may wish to send Push webhook events require a custom HTTP header for authorization. You can configure a custom header for webhooks in the Push admin console.

Go to Settings > Webhooks and add a new webhook. You will see a dropdown option for Custom headers.

Then enter a header key and value. Note that once your header key and value are entered, you will not be able to view them again, as they may contain secrets.

Filtering events

You may wish to send only specific types (or categories) of Push webhook events to your receiver. You can configure this when creating a new webhook in the Push admin console.

Go to Settings > Webhooks and add a new webhook. You will see a dropdown option for Select events.

Then you can select the specific events, or categories of events, to enable. If you select a category, any new events that are added to that category later (as part of new features released) will also be sent.

Download OpenAPI description
webhooks-v1.json
webhooks-v1.yaml
Overview
URL
https://pushsecurity.com/contact/
support
support@pushsecurity.com
License
Commercial
Terms of Service
Servers
https://api.pushsecurity.com/

Activity

Events representing employee activity.

Webhooks

Audit

Audit log events.

Webhooks

Phishing tool detection ignored domains addedWebhook

Request

A set of domains have been added to the list of ignored domains for the Phishing tool detection feature.

Security
X-Signature
Headers
X-Signaturestringrequired
Example: X-Signature: t=1492774577,v1=5257a869...
Bodyapplication/json
versionstringrequired

The version of the event.

Example: "1"
idstring(uuid)required

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

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

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

Example: 1698604061
categorystringrequired

The category of the event.

Value"AUDIT"
objectstringrequired

The object that was created.

Value"PHISHING_TOOL_DETECTION_IGNORED_DOMAINS_ADDED"
actorobject(Admin Audit Log Actor)required

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

actor.​sourcestringrequired

The source of the action that generated the event.

Value"UI"
actor.​emailstringrequired

The email address of the actor.

actor.​sourceIpAddressstringrequired

The IP address of the actor.

actor.​userAgentstring or nullrequired

The user agent of the actor, if available.

actor.​rolestring or nullrequired

The role of the actor.

Enum"FULL_ACCESS""READ_ONLY"
newobjectrequired
new.​domainsArray of stringsrequired

A list of the added domains.

descriptionstring

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 added ignored domains"
friendlyNamestring

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 Detection ignored domains added"

Responses

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

Phishing tool detection ignored domains removedWebhook

Request

A set of domains have been removed from the list of ignored domains for the Phishing tool detection feature.

Security
X-Signature
Headers
X-Signaturestringrequired
Example: X-Signature: t=1492774577,v1=5257a869...
Bodyapplication/json
versionstringrequired

The version of the event.

Example: "1"
idstring(uuid)required

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

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

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

Example: 1698604061
categorystringrequired

The category of the event.

Value"AUDIT"
objectstringrequired

The object that was created.

Value"PHISHING_TOOL_DETECTION_IGNORED_DOMAINS_REMOVED"
actorobject(Admin Audit Log Actor)required

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

actor.​sourcestringrequired

The source of the action that generated the event.

Value"UI"
actor.​emailstringrequired

The email address of the actor.

actor.​sourceIpAddressstringrequired

The IP address of the actor.

actor.​userAgentstring or nullrequired

The user agent of the actor, if available.

actor.​rolestring or nullrequired

The role of the actor.

Enum"FULL_ACCESS""READ_ONLY"
newobjectrequired
new.​domainsArray of stringsrequired

A list of the removed domains.

descriptionstring

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 ignored domains"
friendlyNamestring

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 Detection ignored domains removed"

Responses

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

Reused password exceptions updatedWebhook

Request

The reused password exceptions list has been updated

Security
X-Signature
Headers
X-Signaturestringrequired
Example: X-Signature: t=1492774577,v1=5257a869...
Bodyapplication/json
versionstringrequired

The version of the event.

Example: "1"
idstring(uuid)required

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

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

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

Example: 1698604061
categorystringrequired

The category of the event.

Value"AUDIT"
objectstringrequired

The object that was created.

Value"REUSED_PASSWORD_EXCEPTIONS_UPDATED"
actorobject(Admin Audit Log Actor)required

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

actor.​sourcestringrequired

The source of the action that generated the event.

Value"UI"
actor.​emailstringrequired

The email address of the actor.

actor.​sourceIpAddressstringrequired

The IP address of the actor.

actor.​userAgentstring or nullrequired

The user agent of the actor, if available.

actor.​rolestring or nullrequired

The role of the actor.

Enum"FULL_ACCESS""READ_ONLY"
newobjectrequired
new.​exceptionsArray of stringsrequired

A list of the apps that will not raise reused password findings.

descriptionstring

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 has updated the apps where reused passwords are not raised."
friendlyNamestring

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

Example: "Reused password exceptions updated"

Responses

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

Controls

Events related to any of the control features.

Webhooks

Detections

Webhooks

Entities

Events representing CRUD operations on entities.

Webhooks