Webhook

The webhook notifier of Shodan Monitor sends a POST request to the URL configured in the notifier. It's the recommended way to programmatically receive notifications from Shodan Monitor and it's often combined with serverless infrastructure such as AWS Lambda, Azure Functions or GCP Cloud Run. The below steps guide you through the process of configuring Shodan Monitor to send webhook requests to your URL:

1. Click here to create a webhook notifier

2. Enter the URL and add a short description to help you understand what service the webhook connects with

3. Check Apply to existing asset groups if you want notifications for existing asset groups to use the new webhook

4. Click on Add Notifier

5. Done! You've successfully configured Shodan Monitor to send webhook requests to your URL

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,
          "alert": {
              "id": "XYZ",
              "name": "My Asset Group Name",
              "trigger": "new_service"
          }
      },
      "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

The above information is also available in the _shodan.alert property in the form of a JSON object that looks like:

"alert": {
    "id": "XYZ",
    "name": "My Asset Group Name",
    "trigger": "new_service"
}

Finally, the webhook requests will come from the IP that is associated with the hostname webhook.monitor.shodan.io (currently 138.68.227.220).