Notifications API contract

The API contract for webhook notifications is a one-way data flow.

Request

The request that is made from IBM® Security Verify to the configured webhook URL is an HTTP POST. The Content-Type header is set to application/json and the request body is a single IBM Security Verify event.
Field Value Notes
Method POST  
Resource N/A  
Content-type application/json  
Accept   Unset
HTTP Body See the example. A JSON object that encapsulates a single event.

Request body example

The content of the event varies depending on the event type. The following code is an example of an authentication event:

{
          "geoip": {
            "continent_name": "North America",
            "city_name": "Austin",
            "country_iso_code": "US",
            "ip": "129.42.38.10",
            "country_name": "United States",
            "region_name": "Texas",
            "location": {
              "lon": "-97.7133",
              "lat": "30.4092"
            }
          },
          "data": {
            "result": "success",
            "subtype": "user_password",
            "subject": "50Q4QK9UTM",
            "origin": "129.42.38.10",
            "cause": "Authentication Successful",
            "action": "login",
            "sourcetype": "clouddirectory",
            "realm": "cloudIdentityRealm",
            "devicetype": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.45 Safari/537.36",
            "target": "https://example.verify.ibm.com/",
            "username": "scott@ibm.com"
          },
          "year": 2022,
          "event_type": "authentication",
          "month": 1,
          "indexed_at": 1641825768059,
          "tenantid": "7fc5e889-c27b-4ff0-96f2-a495e0598e78",
          "tenantname": "example.verify.ibm.com",
          "correlationid": "CORR_ID-1112f59a-5ac2-439b-9c73-dc140932c7d2",
          "servicename": "authsvc",
          "id": "d5dc6c25-0060-4078-bb80-1c218cb5e05a",
          "time": 1641825767367,
          "day": 10
        }

For more examples of events, see the events API.

Response

The configured webhook URL responds to a request with an HTTP status of 2XX to indicate that the notification was successfully received. If a non-2XX code is returned, the HTTP body of the response is not read and no response is included.
Field Expected value Notes
Status code 2XX Unless otherwise configured.
Body Empty