Data Theorem supports integrating with customers via webhooks. The guide below will walk you through how to start receiving Data Theorem events via webhook.

The following Data Theorem events can be sent via the webhook integration:

Mobile Secure

When a finding note is created
When a finding note is deleted
When a new finding target is created
When a finding target is fixed
When a finding target is closed and marked “Risk Accepted”
When a finding target is closed and marked “Compensating Control”

API Secure, Web Secure, Cloud Secure

When a policy violation was opened.
When a policy violation was resolved
When a policy violation is closed and marked "Won't Fix“.
When a network service is discovered

Setting up the Webhook Integration

Requirements

A public service, server, or serverless function capable of receiving HTTPS POST requests with JSON body
HTTPS is required
Supported Authentication Methods:
- HTTP Bearer Token Authorization Header (https://tools.ietf.org/html/rfc6750)
- Capability URLs like Slack or MS Teams (https://www.w3.org/TR/capability-urls/)
- No Authentication (Not Recommended)

Step 1: Confirm Your Webhook Endpoint Is Configured Correctly

To confirm your webhook endpoint is configured correctly, run the command below and confirm that it succeeds.

If Your Webhook Endpoint Uses HTTP Bearer Token Authentication:

curl -k "https://<your webhook url>" \
   -H "Authorization: Bearer <your bearer token>" \
   -H "Content-Type: application/json" \
   -d '{"event": "Hello, world!"}'

If Your Webhook Endpoint Uses URL Authentication or No Authentication:

curl -k "https://<your webhook url>" \
   -H "Content-Type: application/json" \
   -d '{"event": "Hello, world!"}'

Step 2: Enable Webhook Integration

Email to support@datatheorem.com the following information:

Name Of Integration (may contain letters, numbers, dashes, underscores, and spaces)
Webhook URL
Optional
- HTTP Bearer Token Authorization Header Value. Example: Bearer 123456abcde

Here a template you may use to when emailing Data Theorem support to enable the webhook integration:

Please enable a webhook integration for <ORGANIZATION> using the following settings:

Name: <NAME FOR YOUR INTEGRATION LIKE "SPLUNK" OR "CUSTOM WEBHOOK-1">
URL: <WEBHOOK URL>
<IF USING HTTP BEARER TOKEN AUTH>
Authorization Header Value: <BEARER TOKEN>

You will receive a reply from Data Theorem once your integration has been enabled. Once your webhook integration is enabled your webhook endpoint will begin receiving events in real time from Data Theorem.

Events

The format of events to be sent via the webhook integration is available at https://datatheorem.atlassian.net/wiki/spaces/PKB/pages/656310320/Webhook+Event+Message+Format?moved=true .

Example Event

{
  "event": {
    "type": "API_SECURE__POLICY_VIOLATION_RESOLVED",
    "data": {
      "uuid": "924f1fb0-ebaa-4dfd-9297-390c0df18b44",
      "affected_asset": {
        "uuid": "ed1d9485-5672-4db0-81aa-f8e5c96ba750",
        "name": "gumtree.com.au",
        "portal_url": "https://dev-acheron.appspot.com/api/network-services/ed1d9485-5672-4db0-81aa-f8e5c96ba750",
        "date_created": "2020-07-23T08:18:30.450602+00:00",
        "discovered_via": "WEBSITE_CRAWLER",
        "url": "https://gumtree.com.au",
        "hosted_on": "UNKNOWN",
        "type": "NETWORK_SERVICE",
        "cloud_console_url": null
      },
      "policy_violation_status": "RESOLVED",
      "date_created": "2021-01-19T12:04:15.714371+00:00",
      "relevance": "IMPORTANT",
      "description": "The server leverages a certificate for SSL/TLS connections that will expire in less than the configured number of days.\\n\\nIf the SSL certificate is not renewed in time, clients including browsers and mobile applications will not allow\\nconnecting to the server, and will instead display an error to the end-user stating that the connection is not secure.",
      "recommendation": "Deploy a new SSL/TLS certificate on the affected server.",
      "additional_information": null,
      "portal_url": "https://dev-acheron.appspot.com/api/inspect/policy-violations/924f1fb0-ebaa-4dfd-9297-390c0df18b44",
      "policy_name": "Data Theorem",
      "policy_uuid": "17e0e14d-e6f1-4b35-a5c0-976dbbf41436",
      "policy_portal_url": "https://dev-acheron.appspot.com/api/policy/17e0e14d-e6f1-4b35-a5c0-976dbbf41436",
      "violated_policy_rule_uuid": "471284cb-e96a-49e0-a729-674cfe18f506",
      "violated_policy_rule_type_uuid": "5c3b1f37-8509-5c6e-abed-6ee9f3497c17",
      "exception_explanation": null,
      "exception_date_created": null
    },
    "version": 1
  },
  "time": 1611733052,
  "host": "securetheorem.com"
}

Webhook Integration