Working with the Shodan Monitor webhook

Shodan Monitor helps you keep track of what you have exposed to the Internet. There are a few ways that Monitor sends out notifications (email, Slack, etc.) but the one we'll discuss in this article is aimed at developers: webhook notifications.

Registering a webhook

To let Shodan Monitor know about your webhook you need to add it from the Settings page:

1. Select the option Webhook in the dropdown
2. Click Add
3. Enter the URL and add a short description to help you understand what service the webhook connects with
4. Submit the form by clicking Add Notifier

Enabling the webhook

Just registering the webhook isn't enough for Shodan to start sending notifications to it. You need to also add the webhook as a notification endpoint in your network alerts. If you're creating a new alert then you will see it as an option in the Notification Services section. Otherwise click the gear icon in your Manage Assets page for the alerts that you'd like to enable webhooks on.

Receiving the data

You've got your web service up and running, you've registered and enabled your webhook, and now it's time to actually process the incoming data that Monitor will send. The webhook notification does a POST request to your URL where:

• The body of the POST request contains a JSON-encoded banner
• The header of the POST request contains information about the alert

The JSON-encoded banner is exactly the same as you'd get from doing a search query via the API or by doing IP lookups. Here is a short example:

{
    "asn": "AS15169", 
    "hash": -553166942, 
    "ip": 134744072, 
    "isp": "Google", 
    "transport": "udp", 
    "data": "\nRecursion: enabled", 
    "port": 53, 
    "hostnames": [
        "google-public-dns-a.google.com"
    ], 
    "location": {
        "city": null, 
        "region_code": null, 
        "area_code": null, 
        "longitude": -97.822, 
        "country_code3": "USA", 
        "latitude": 37.751000000000005, 
        "postal_code": null, 
        "dma_code": null, 
        "country_code": "US", 
        "country_name": "United States"
    }, 
    "timestamp": "2018-03-16T03:06:34.553526", 
    "domains": [
        "google.com"
    ], 
    "org": "Google", 
    "os": null, 
    "_shodan": {
        "crawler": "6ff540e4d43ec69d8de2a7b60e1de2d9ddb406dc", 
        "options": {}, 
        "module": "dns-udp", 
        "id": null
    }, 
    "opts": {}, 
    "ip_str": "8.8.8.8"
}

The headers contain metadata about the alert to help you understand which alert was responsible for generating the notification. Specifically, the following headers are available in the POST request:

• SHODAN-ALERT-ID: unique ID for the alert
• SHODAN-ALERT-NAME: name for the alert
• SHODAN-ALERT-TRIGGER: trigger that caused the notification to get sent
• SHODAN-SIGNATURE-SHA1: SHA1 signature encoded using your API key to validate the notification's origin

Have further questions or not sure how to integrate webhooks? Reach out to support@shodan.io for further assistance.