Callback API (WebHooks)

View product develop

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

Callbacks Configuration

Callbacks are configured via database. 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', 
    '["type", "operationId", "userId", "applications", "operationType", 
    "parameters", "additionalData", "activationFlag", "status", 
    "data", "failureCount", "maxFailureCount", "signatureType", 
    "externalId", "timestampCreated", "timestampExpires", "timestampFinalized"]');

Last updated on Oct 16, 2023 (15:37) View product