Webhooks

This page outlines how Webhooks work in Zenlogin, and the different Webhook events available.

Webhooks

There are currently 6 different Webhook events that are fired by Zenlogin to the Webhook URL you've set up. When these events fire, they contain data that you can use to trigger your own internal logic.

The primary purpose of these Webhooks is to ensure your system is kept up to date with the status or state of your user's security.

Response HTTP Status Code & Retry Attempts

The HTTP Response from any Webhooks must be a 200 status code. This tells our server that the Webhook has been successfully received.

If the Webhook responds with anything except a 200 HTTP status code, then Zenlogin will re-attempt the webhook (up to 5 times) until it receives a 200 status code response.

This will take place over 5-minutes (1 webhook attempt per minute) until it receives a successful 200 HTTP status code, or the maximum number of attempts has been reached.

Verifying Responses

For added security, when using Webhooks you can verify that each webhook is in fact coming from Zenlogin. To do so, please follow the steps below:

  1. Create a comparison signature: use your Webhook URL and secret key to create a comparison signature (using the sha256 algorithm).
  2. Extract the Zenlogin signature: Zenlogin sends it's signature in the X-SIGNATURE header. Note that if you're using Cloudflare, this header key/name may be modified before reaching your server (e.g. X-SIGNATURE becomes HTTP_X_SIGNATURE).
  3. Compare the two signatures: these signatures should match. If they do, you can proceed with processing the webhook with full confidence that it originates from Zenlogin.

Below you can see an example of doing this in PHP: 

$payload = '{{zenlogin webhook URL}}';
$secretKey = 'sk_live_00000000000000000000000000000000';
$comparisonSignature = hash_hmac('sha256', $payload, $secretKey);
$receivedSignature = $_SERVER['HTTP_X_SIGNATURE'] ?? null;
$valid = $comparisonSignature === $receivedSignature;
var_dump($valid);

Test Requests

Test requests do not trigger webhooks. For example, when you use the Preview or Send preview options on the Email Customization page in the Admin, those will not trigger the applicationLoginCheck.ruleApplied webhooks.

Webhook Events

Below is a list of the Webhook events currently triggered by Zenlogin.

Event Details
account.created This event is fired when your account is first created. This assumes that during the creation process, you specified a Webhook URL. Currently, this is only relevant for WordPress integrations.
account.setup.complete This event is fired when your account has been successfully been setup. At the moment, this means you've confirmed your email address. Currently, this is only relevant for WordPress integrations.
application.disabled This event is fired when your application's Zenlogin integration is turned off. This is controlled via your Account Settings page.
application.enabled This event is fired when your application's Zenlogin integration is turned on. This is controlled via your Account Settings page.
applicationLoginCheck.ruleApplied This event is fired when a security rule has been applied, indicating that the user should be notified of a potential security issue.
webhook.test This event is fired periodically to test your webhook. It's also fired immediately after specifying a Webhook URL.

Webhook Responses

account.created 

{
    "success": true,
    "data": {
        "type": "account.created",
        "accessToken": "********************************",
        "account": {
            "publicId": "accn1abtwskjj3q1"
        },
        "application": null
    }
}

account.setup.complete 

{
    "success": true,
    "data": {
        "type": "account.setup.complete",
        "accessToken": "********************************",
        "account": {
            "publicId": "accn1abtwskjj3q1"
        },
        "application": {
            "publicId": "applrn12zr5zayrp"
        }
    }
}

application.disabled 

{
    "success": true,
    "data": {
        "type": "application.disabled",
        "account": {
            "publicId": "accn1abtwskjj3q1"
        },
        "application": {
            "publicId": "applrn12zr5zayrp"
        }
    }
}

application.enabled 

{
    "success": true,
    "data": {
        "type": "application.enabled",
        "account": {
            "publicId": "accn1abtwskjj3q1"
        },
        "application": {
            "publicId": "applrn12zr5zayrp"
        }
    }
}

applicationLoginCheck.ruleApplied 

{
    "success": true,
    "data": {
        "type": "applicationLoginCheck.ruleApplied",
        "account": {
            "publicId": "accn1abtwskjj3q1"
        },
        "application": {
            "publicId": "applrn12zr5zayrp"
        },
        "applicationIdentity": {
            "publicId": "apid1tv26zhtx2zy",
            "identityKey": "usr012s9zbs5b2ro",
            "identityEmailAddress": "oliver@zenlogin.co",
            "identityFirstName": "",
            "identityLastName": "",
            "identityFullName": ""
        },
        "applicationLoginCheck": {
            "publicId": "alch39ztz6gg65as",
            "reqTest": true,
            "ipAddress": {
                "publicId": "ipadl53b436jbexx",
                "ipAddress": "2607:fea8:3a9e:5e00:89e3:c998:abf4:3e13",
                "label": "Richmond Hill, Canada",
                "countryCode2": "ca",
                "lat": "43.86780166626",
                "long": "-79.442001342773"
            },
            "userAgent": {
                "publicId": "usagtxcy386y2v21",
                "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.192 Safari/537.36",
                "browserName": "Chrome",
                "browserVersion": "88.0.4324.192",
                "browserVersionMajor": "88",
                "deviceLabel": "Apple Mac",
                "deviceName": "Mac",
                "deviceType": "Desktop",
                "isMobileDevice": false
            },
            "applicationAPIRequest": {
                "publicId": "aarq1i3n636y83az",
                "requestId": "req_27457tl394fhozgz5xwv92wwq5raf9qs"
            }
        }
    }
}

webhook.test 

{
    "success": true,
    "data": {
        "type": "webhook.test",
        "account": {
            "publicId": "accn1abtwskjj3q1"
        },
        "application": {
            "publicId": "applrn12zr5zayrp"
        }
    }
}