Webhooks

Webhook format

Note: The geolocation data included in the webhook payload, such as city, longitude and latitude, is inferred from the provided IP address and may deviate from the user’s actual location. IP geolocation is more accurate for land-line and cable networks and less accurate for mobile networks.

The payload of the webhook delivered by Castle is a JSON document with the following fields:

FieldDescription
api_versionCastle API version. This is set to “v1.”
app_idApplication ID of your Castle environment.
typeSecurity event type.
created_atTime when the security event was triggered.
data.idA unique webhook identifier.
data.device_tokenDevice token, referencing the device that caused the security event.
data.user_idThe user ID of the user that caused the security event.
data.triggerThe Castle event that triggered the security event.
data.context.ipIP address of the request that caused the security event.
data.context.ispObject with additional information about the ISP that is tied to the IP address.
data.context.locationObject with additional information about the location that is tied to the IP address. Location information, such as country, can be useful to present to the user when sending out notifications.
data.context.user_agentObject with information about the UserAgent of the device that caused the security event. In addition to the raw UserAgent it also contains parsed values (for example, which OS and software was used). Device information, such as OS and browser name, can be useful to present to the user when sending out notifications.
data.user_traitsUser traits object that were sent with the original request that triggered the security event
data.propertiesProperties that were sent with the original request that triggered the security event
data.policyObject with information about which policy triggered the action.

Example webhook payload:

{
  "api_version": "v1",
  "app_id": "382395555537961",
  "type": "$incident.confirmed",
  "created_at": "2020-10-01T19:38:28.483Z",
  "data": {
    "id": "test",
    "device_token": "eyJhbGciOiJI1NiJ9.eyJ0b2tlbiI6InRlc3QiLCJzaW9uIjowLjF9._-0l6TlDH7m78l19z1amMQ02m7s",
    "user_id": "2",
    "trigger": "$login.succeeded",
    "context": {
      "ip": "1.2.3.4",
      "isp": {
        "isp_name": "CastleNet",
        "isp_organization": "Castle"
      },
      "location": {
        "country_code": "US",
        "country": "United States",
        "region": "Massachusetts",
        "region_code": "MA",
        "city": "Boston",
        "lat": 42.3292,
        "lon": -71.0263
      },
      "user_agent": {
        "raw": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:75.0) Gecko/20100101 Firefox/75.0",
        "browser": "Firefox",
        "version": "75.0",
        "os": "Mac OS X 10.15",
        "mobile": false,
        "platform": "Mac OS X",
        "device": "Unknown",
        "family": "Firefox"
      }
    },
    "user_traits": {
      "email": "test@example.com"
    },
    "properties": {
      "amount": "1000"
    },
    "policy": {
      "id": "cy_TIbBlS9WIqqNdHZ20tA",
      "revision_id": "cG2WKpiNQOOvmU0LGg8IJw",
      "name": "My Policy",
      "type": "authentication",
      "action": "deny"
    }
  }
}