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 two 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).

When using mTLS certificate authentication, make sure to map a volume with your keystore and truststore files to the running container volumes, so that the application can access the files on a specified location.

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).

It is possible to customize which of the data fields are sent in the callback payload. For operation callbacks, only type and operationId are mandatory fields in the callback. For registration callbacks, the type and activationId are mandatory.

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",
    "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"
}
Field Type Description
type Enum Discriminator, uses OPERATION value for operation callbacks
operationId UDID Operation ID
userId String User ID
applications String[] Array of Application ID the operation is created for (there could be multiple IDs if user has multiple registration of multiple Applications)
operation_type String Type of the operation, i.e., login or authorize_payment
parameters Map<String, String> Key-value map with operation parameters
additionalData Map<String, Object> Additional data stored within the operation, such as activation identifier used for approving the operation or information about the device relevant to the operation
activationFlag String Activation flag used for a operation creation
status Enum Operation status, one of PENDING, CANCELED, EXPIRED, APPROVED, REJECTED or FAILED.
data String Data used for signature
failureCount Int Counter indicating how many times did the operation failed
maxFailureCount Int Maximum value of allowed failures
signatureType String Allowed signature types for given operation
externalId String External operation ID (for identification in third-party systems)
timestampCreated DateTime Timestamp when the operation was created
timestampExpires DateTime Timestamp of when the operation expires
timestampFinalized DateTime Timestamp when the operation reached a final state, i.e., when was confirmed.

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"
}
Field Type Description
type Enum Discriminator, uses OPERATION value for operation callbacks
activationId UDID Registration ID (internally, called “activation”)
userId String User ID
activationName String Displayable name of the registration
deviceInfo String Basic information about the device model
platform String Basic information about the platform (iOS, Android)
protocol String Authenticator protocol (powerauth, fido)
activationFlags String[] Freeform flags assigned to the registration
activationStatus Enum Registration status, one of CREATED, PENDING_COMMIT, ACTIVE, BLOCKED or REMOVED
blockedReason String If the registration is blocked, the field contains a blocking reason info
applicationId String Application ID

Callbacks Configuration

Since 1.7.0 the callbacks can be configured via Admin API . The callback using mTLS authentication can be currently configured only in a database.

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"]');
Last updated on Jun 17, 2024 (09:08) View product
Search

1.8.x

PowerAuth Cloud