Webhooks

Webhooks enables your server to be told about users' Upollo flags in real time, allowing you to act on repeated trials and account sharing.

Sign up for Upollo

Sign up at app.upollo.ai/login to set your webhook URLs and to get your webhook secret key.

Getting started

First you will need to setup a webhook URL which can be done under webhooks on the Access & Keys page in the Upollo developer centre. We strongly recommend using https urls for your webhooks.

Once you have added a URL you will be given a webhook key which you can use to verify the signature of the responses if you wish.

Webhook request structure

Below is a formatted example webhook JSON payload.

{
  "analysis": {
    "action": "CHALLENGE",
    "flags": [
      {
        "type": "MULTIPLE_ACCOUNTS",
        "firstFlagged": "2022-04-13T03:48:09.041096Z",
        "mostRecentlyFlagged": "2022-04-13T03:48:09.041096Z"
      },
      {
        "type": "ACCOUNT_SHARING",
        "firstFlagged": "2022-04-13T03:48:11.208795Z",
        "mostRecentlyFlagged": "2022-04-13T03:48:11.208795Z"
      },
      {
        "type": "ACCOUNT_SHARING_SAME_HOUSEHOLD",
        "firstFlagged": "2022-04-13T03:48:11.208797Z",
        "mostRecentlyFlagged": "2022-04-13T03:48:11.208797Z"
      }
    ],
    "userInfo": {
      "userID": "user",
      "userEmail": "user@domain.com"
    },
    "deviceInfo": {
      "deviceID": "cKmLrgoy7nX5Hnb24KMQyy",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.75 Safari/537.36"
    },
    "requestID": "5959061a-5a74-4596-99c1-908a2a053cae",
    "supportedChallenges": ["CHALLENGE_TYPE_SMS"],
    "eventType": "LOGIN",
    "emailAnalysis": {
      "valid": true,
      "emailType": "EMAIL_TYPE_PUBLIC",
      "provider": "EMAIL_PROVIDER_GOOGLE"
    },
    "multiAccountingMatchedUsers": [
      {
        "userId": "u_123",
        "userEmail": "matched_user@example.com"
      }
    ]
  },
  "timestamp": "2022-04-13T03:48:20.134747Z"
}

Verifying the webhook request

Each request has a "Upollo-Signature" header which contains a two part signature made up "t:" followed by a timestamp in seconds and "s0:" followed by the SHA512 hash of the JSON payload.

To verify the signature, compute a HMAC with the SHA512 hash function using your webhook secret key as the key and the JSON payload as the message. Compare this signature to the one you received in the "Upollo-Signature" header.