Documentation

Documentation to build on the Passmarked platform

Websockets

Passmarked itself was built to be near realtime by sending out data over websockets as events are fired in the system. This allows users to build apps that update with the progress and information of a webpage in realtime. Making good looking UI's possible.

Connecting

Passmarked runs a open Websocket server that any client can connect to and listen for information about events in the system.

The servers are located at:

ws://wss.passmarked.com

The servers support both ws:// and wss:// for encrypted connections.

To check if the connection is working we advice a debug tools like wscat. Try the following to debug with wscat:

 npm install wscat -g
wscat -c ws://wss.passmarked.com

Protocol

All messages delivered are done in JSON. The server does not allow any interaction with the platform. Instead it allows anyone with the correct secrets to listen for events.

The servers are meant for quick connections to listen for a limited set of data and built as such with a few limitations:

No more than 10 key subscriptions per connection
No more than 25 connections from a single IP is allowed. The rest will be killed as soon as they connect.
Connections lasting more than an hour will be disconnected.

Events

The Passmarked platform send out numerous events over WebSockets to all clients listening for subscribed keys.

Subscribing to events

To subscribe to a key, the following data must be send over the connected websocket:

{ "key": "(key-to-subscribe)" }

The key being sent must be bigger than 0 characters and no longer than 120 characters else the request will be ignored.

Unsubscribing from events

When the desired events have been received, it is good form to unsubscribe from the key. And maybe disconnect if no more operations are required for the context over the single connection.

To tell the server to remove the subscription, send the following JSON payload over the websocket:

 { "key": "(key-to-remove)", "action": "remove" }

Possible events that can be received

The following events can be subscribed and received by clients. It should be noted that there are no restrictions on the names, it simply means anything other than the listed keys will never receive data and get disconnected after an hour.

NameDescription
welcomeWelcome message, serving as a notification that the connection is working, every time the clients connects to any of the servers. By default this is sent to all clients, no need to subscribe.
pingSend a payload to show that the connection is alive every 10 seconds. By default this is sent to all clients, no need to subscribe. Users are expected to build in retry events for cases where the timeout has not been received for more than 30 seconds.
reports.(report-uid)All events send out related to the report, this includes numerous events that indicate information unique to that phase of checking a report. The event allows realtime UI's that update as the report is running, see Report Events
users.(user-secret)Any events related to the user themselves, such as credit usage and new bundles, see User Events
websites.(website-secret)Any events related to the website itself. This includes events like a new recursive report which started and more, see Website Events

Report Events

Reports run using the system generate a few events which client apps/integrations can react on when connected to the web sockets.

It should be noted that using WebSockets are not required and the data can be polled instead as noted in View Report.

The following events are produced during reports, and can be set on the event property in the payload:

NameDescription
sessionWhen running a recursive report, the event will contain data about the status of the recursive walk through the site itself. Including how many pages and the status of the session in its entirety.
pageContains data about the current page being tested. In recursive reports these simply indicate the status of individual pages. In single page reports these events indicate and show the status of the page being tested. The possible states of a page include: pending, running, testing and done
testFired when the status of a test is changed. The test will fire the event 3 times, mainly when:
  • The test is starting to run: active
  • The test is finished (done) in which case the result property will also be set with the ending result of the test
issueContains data about an issue found in the report. These issues can be built up to give a local list of issues found without calling the API again

User Events

Events are fired when a update to the user occurs. These might include credit usage or profile updates to name a few.

The following events are produced during updates to users, and can be set on the event property in the payload:

NameDescription
balanceThe balance of the user was updated, mainly used to show the current amount of credits available to the user

Website Events

Events are fired when a update to any of the websites occur. These might include credit usage or new recursive reports starting which will mark the website as busy.

The following events are produced during updates to users, and can be set on the event property in the payload:

NameDescription
updateUpdate to the settings/data of the website itself. Allows quick updates to UI's if needed
reportInformation about a new recursive report that has been started
Signup icon
Ready to see how well your site scores?

Passmarked works best when you have an account. It allows you to keep a dashboard with saved data of the sites you have run through the system, we’ll alert you about important updates and you get access to the Passmarked Slack forum.

Sign up to get started