Introducing webhooks

Posted on

PatrolServer webhooks are officially available to all our users. As of today, developers are able to integrate PatrolServer within all their favourite applications. So next to polling the results of our scans with our API, we introduce a push mechanism to get information when something has changed.

What are webhooks?

Webhooks are real time events to alert you whenever an event occurs in PatrolServer. For example, your server finished scanning and has new issues. A webhook will be triggered and as a developer, you can now interact based on this new information.

The webhooks are HTTP POST requests, delivered to a destination URL entered in the API settings page. Each time a new event occurs, we’ll perform this action on the URL(s) of your choice.

Let’s take the following use case: new composer package issues have been found on your server. You intercept this with our webhook and automatically run thecomposer update command. Or, what if you’d like to send a message to Slack when your server software suddenly became outdated.

For implementation details, check the API webhooks documentation page.

Awesome! How does this work technically?

As you may have noticed, we make it our daily job to be as secure as possible. Webhooks security makes no difference. We work in three steps:

  1. When an event occurs on PatrolServer, we create an Event object on our server. We then send a JSON message to the webhooks URLs configured in your API settings page, containing a webhook_id and an event_id. No other event information is sent and so no other information can be intercepted.
  2. To get the Event object information,  you will need to fetch it fromhttps://api.patrolserver.com/webhooks/{webhook_id}/events/{event_id} with your API key and secret.
  3. You can then do whatever you want with the information retrieved from the API.

Which events are supported?

Event name Description
webhook.scan_started When our scanner is started both manually by pressing the button or automatically by our daily scan, this event will be sent
webhook.new_server_issues When a new issue has been found by our engine, this event will be triggered. Only new issues that arise will be sent. If you want daily status update of all remaining issues, you need to use the scan_finished event and get the date from our API.
webhook.scan_finished When a manually of automatically scan is done, this event will get sent. You get the server_id, so you can lookup all found issues with our API.

Let’s get started!

Login to PatrolServer and navigate to the API page (click on your email address in the right, top corner and select API).

Enter your webhook URL and you’re all set. Whenever an event occurs, we’ll send a request to that particular URL (or multiple, you can add more than one webhook).

Slack Integration

For the avid Slack users, we’ve made our webhooks compatible with Slack. When you visit the API page, you’ll notice a small Slack icon on the right bottom corner. All it takes is entering an Incoming Webhook URL and our system does the rest.

When you’ve successfully entered the Incoming Webhook URL, your Slack channel will be able to get messages from the PatrolServer Slack Bot as shown below: