Callback API (WebHooks)

External systems that integrate with the PowerAuth Cloud components can obtain status about registration and operation change by polling the appropriate API resources. However, this may either put unnecessary performance burden on our systems when the polling is too frequent, or provide sub-optimal user experience when the polling is occasional.

To provide an instant notification about changes in our systems, PowerAuth Cloud can notify your systems via a callback (sometimes called “webhooks”) whenever registration or operation changes.

Callback Authentication

Callbacks support following authentication methods:

• HTTP Basic Authentication - Authentication using username and password.
• Certificate Authentication (mTLS) - Authentication using a client certificate with a custom keystore and truststore (i.e., JKS).
• OAuth2 Authentication - Authentication using OAuth 2.0 client credentials grant type.

Callback Types

There are two callback types:

• Operation Callbacks - Called whenever operation status changes.
• Registration Callbacks - Called whenever registration status changes.

The callback type is distinguished by the type discriminator value in the root of the JSON payload, which is either set to the OPERATION_STATUS_CHANGE value (for operation callbacks) or REGISTRATION_STATUS_CHANGE value (for registration callbacks).

Operation Callbacks

{
  "type": "OPERATION_STATUS_CHANGE",
  "operationId": "$OPERATION_ID",
  "userId": "$USER_ID",
  "applications": "[$APPLICATION_ID1, ... , $APPLICATION_ID1]",
  "operationType": "$OPERATION_TYPE",
  "parameters": {
    "key1": "$VAL1",
    "key2": "$VAL2"
  },
  "additionalData": {
    "activationId": "$ACTIVATION_ID",
    "ipAddress": "172.168.240.48",
    "userAgent": "PowerAuthNetworking/1.3.0 (en; wifi) com.wultra.app.MobileToken/2.0.0 (Apple; iOS/17.3.1; iphone16,1)",
    "device": {
      "networkVersion": "1.3.0",
      "language": "en",
      "connection": "wifi",
      "product": "com.wultra.app.MobileToken",
      "version": "2.0.0",
      "platform": "Apple",
      "os": "iOS",
      "osVersion": "17.3.1",
      "model": "iphone16,1"
    }
  },
  "activationFlag": "MTOKEN",
  "status": "$STATUS",
  "data": "$OPERATION_DATA",
  "failureCount": 0,
  "maxFailureCount": 5,
  "signatureType": "$SIGNATURE_TYPE",
  "externalId": "$EXTERNAL_ID",
  "timestampCreated": "$TIMESTAMP_CREATED",
  "timestampExpires": "$TIMESTAMP_EXPIRES",
  "timestampFinalized": "$TIMESTAMP_FINALIZED"
}

The operation callback can contain the following attributes, which can be customized via the Admin API.

Registration Callbacks

{
  "type": "REGISTRATION_STATUS_CHANGE",
  "activationId": "$ACTIVATION_ID",
  "userId": "$USER_ID",
  "activationName": "$ACTIVATION_NAME",
  "deviceInfo": "$DEVICE_INFO",
  "platform": "$PLATFORM",
  "protocol": "$PROTOCOL",
  "activationFlags": [
    "$ACTIVATION_FLAGS"
  ],  
  "activationStatus": "$ACTIVATION_STATUS",
  "blockedReason": "$BLOCKED_REASON",
  "applicationId": "$APPLICATION_ID"
}

The registration callback can contain the following attributes, which can be customized via the Admin API.

Callbacks Configuration

Since version 1.7.0 the callbacks can be configured via Admin API .

When creating or updating the callback, you may specify the parameter attributes, which is a JSON array of strings. This parameter defines which attributes will be included in the callback payload. If the attributes parameter is not specified, the default set of attributes is used.

An operation callback can contain the following values:

• userId
• applications
• operationType
• parameters
• additionalData
• activationFlag
• status
• data
• failureCount
• maxFailureCount
• signatureType
• externalId
• timestampCreated
• timestampExpires
• timestampFinalized

A registration callback can contain the following values:

• userId
• activationName
• deviceInfo
• platform
• protocol
• activationFlags
• activationStatus
• blockedReason
• applicationId

For details, see Registration Callbacks and Operation Callbacks.

Database Configuration

Database callbacks configuration is stored in table pa_application_callback. Example of operation callback with multiple attributes and enabled basic HTTP authorization.

INSERT INTO pa_application_callback (id, 
    application_id, 
    name, 
    type, 
    authentication, 
    callback_url,
    attributes)
VALUES (uuid_generate_v4(), 
    1, 
    'operation-callback', 
    'OPERATION_STATUS_CHANGE', 
    '{
      "certificate" : null,
      "httpBasic" : {
        "enabled": true,
        "username": "basic_http_username",
        "password": "basic_http_password"
      }
    }',
    'http://localhost:8080/your_app/operation/status/update', 
    '[ "userId", "applications", "operationType", 
    "parameters", "additionalData", "activationFlag", "status", 
    "data", "failureCount", "maxFailureCount", "signatureType", 
    "externalId", "timestampCreated", "timestampExpires", "timestampFinalized"]');