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 value (for operation callbacks) or ACTIVATION value (for registration callbacks).

Operation Callbacks

{
  "type": "OPERATION",
  "operationId": "$OPERATION_ID",
  "userId": "$USER_ID",
  "applications": "[$APPLICATION_ID1, ... , $APPLICATION_ID1]",
  "operationType": "$OPERATION_TYPE",
  "parameters": {
    "key1": "$VAL1",
    "key2": "$VAL2"
  },
  "additionalData": {
    "activationId": "$ACTIVATION_ID",
    "applicationId": "mobile-token",
    "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.

Operation Callback additionalData Payload

The additionalData object in an operation callback corresponds to the operation additional data stored with the operation. The callback contains the current value of the operation additional data at the time the callback is emitted. The additionalData object is optional and is populated as the Mobile Token SDK attempts to approve or reject the operation. The fields in the additionalData object are preserved across attempts. Subsequent attempts may add new values or overwrite existing ones but do not delete previously stored fields.

Complete Fields of additionalData

The additionalData for Approved Operation

The additionalData for Rejected Operation

The additionalData for Failed Attempt

When an approval or rejection attempt fails due to an incorrect signature, the additionalData object is populated with the ipAddress, userAgent, and device attributes. This data is then included in the callback if the operation later expires or is canceled via API.

Fields Parsed from the User-Agent

The device object depends on parsing of userAgent attribute.

Registration Callbacks

{
  "type": "ACTIVATION",
  "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.

Callback Retry Behavior

By default, callbacks are sent only once. The delivery may be retried after a failed attempt, depending on the configured retry settings. For details about retry-related configuration options, see Admin API.

Callback HTTP requests include the Idempotency-Key header. Its value is a unique UUIDv4 that identifies a callback event delivery. If the same callback event is retried, subsequent HTTP requests use the same Idempotency-Key value, allowing the receiving system to recognize duplicate delivery attempts and process them idempotently.