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. All other fields can be left out, the examples below show the maximal callback payloads.

Operation Callbacks

{
    "type": "OPERATION",
    "operationId": "$OPERATION_ID",
    "userId": "$USER_ID",
    "applicationId": "$APPLICATION_ID",
    "operationType": "$OPERATION_TYPE",
    "data": "$OPERATION_DATA",
    "signatureType": "$SIGNATURE_TYPE",
    "status": "$STATUS",
    "parameters": {
        "key1": "$VAL1",
        "key2": "$VAL2"
    },
    "failureCount": 0,
    "maxFailureCount": 5,
    "externalId": "$EXTERNAL_ID",
    "timestampCreated": "$TIMESTAMP_CREATED",
    "timestampFinalized": "$TIMESTAMP_FINALIZED",
    "timestampExpires": "$TIMESTAMP_EXPIRES"
}
Field Type Description
type Enum Discriminator, uses OPERATION value for operation callbacks
operationId UDID Operation ID
userId String User ID
applicationId Int Application ID
operation_type String Type of the operation, i.e., login or authorize_payment
data String Data used for signature
signatureType String Allowed signature types for given operation
status Enum Operation status, one of PENDING, CANCELED, EXPIRED, APPROVED, REJECTED or FAILED.
parameters Map<String,String> Key-value map with operation parameters
failureCount Int Counter indicating how many times did the operation failed
maxFailureCount Int Maximum value of allowed failures
externalId String External operation ID (for identification in third-party systems)
timestampCreated DateTime Timestamp when the operation was created
timestampFinalized DateTime Timestamp when the operation reached a final state, i.e., when was confirmed.
timestampExpires DateTime Timestamp of when the operation expires

Registration Callbacks

{
  "type": "ACTIVATION",
  "activationId": "$ACTIVATION_ID",
  "userId": "$USER_ID",
  "applicationId": "$APPLICATION_ID",
  "activationStatus": "$ACTIVATION_STATUS",
  "blockedReason": "$BLOCKED_REASON",
  "activationName": "$ACTIVATION_NAME",
  "platform": "$PLATFORM",
  "deviceInfo": "$DEVICE_INFO",
  "activationFlags": [
    "$ACTIVATION_FLAGS"
  ]
}
Field Type Description
type Enum Discriminator, uses OPERATION value for operation callbacks
activationId UDID Registration ID (internally, called “activation”)
userId String User ID
applicationId Int Application ID
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
activationName String Displayable name of the registration
platform String Basic information about the platform (iOS, Android)
deviceInfo String Basic information about the device model
activationFlags String[] Freeform flags assigned to the registration
Last updated on Dec 28, 2022 (20:40) View product
Search

1.5.x

PowerAuth Cloud