Callback URLs

Transaction Callback

You can receive notifications via a callback whenever there are new transactions associated with a Record, including when Okra initial and historical transaction pull are completed. All callbacks related to transactions have a callback_type of TRANSACTIONS.

The callback must be in the standard format of http(s)://(www.)domain.com/. The response will contain a corresponding success message and code along with the same record ID that was returned in the initial call (examples below). Once the transaction processing has finished, you can use the Record's token to collect the full account and transaction information for that user.

All transactions callbacks will have a callback_type equal to TRANSACTIONS. Each callback payload will also include a unique callback_code and the record_id for which the callback is being fired.

Initial transaction callback

{
  "callback_type": "TRANSACTIONS",
  "callback_code": "INITIAL_TRANSACTIONS",
  "record": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null,
  "new_transactions": 19
}

Historical transaction callback

{
  "callback_type": "TRANSACTIONS",
  "callback_code": "FULL_TRANSACTIONS",
  "record": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null,
  "new_transactions": 231
}

Default transaction callback

{
  "callback_type": "TRANSACTIONS",
  "callback_code": "PERIODIC_TRANSACTIONS",
  "record": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null,
  "new_transactions": 3
}

Removed transaction callback

{
  "callback_type": "TRANSACTIONS",
  "callback_code": "TRANSACTIONS_DELETED",
  "record": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "removed_transactions": [
    "yBVBEwrPyJs8GvR77N7QTxnGg6wG74H7dEDN6",
    "kgygNvAVPzSX9KkddNdWHaVGRVex1MHm3k9no"
  ],
  "error": null
}
`

Record Callback

Callbacks are also used to communicate changes to a Record such as an updated callback, or errors encountered with a Record. The error typically requires user action to resolve, such as when a user changes their password. For a complete list of possible errors, see Errors.

The callback must be in the standard format of http(s)://(www.)domain.com/. The response will contain a corresponding success message and code along with the same record_id that was returned in the initial call (examples below). Once the transaction processing has finished, you can use the Record's token to collect the full account and transaction information for that user.

All transactions callbacks will have a callback_type equal to TRANSACTIONS. Each callback payload will also include a unique callback_code and the record_id for which the callback is being fired.

Record's callback updated callback

{
  "callback_type": "RECORD",
  "callback_code": "WEBHOOK_UPDATE_ACKNOWLEDGED",
  "record": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null,
  "new_callback_url": "https://okra.ng/example/callback"
}

Record error callback

{
  "callback_type": "RECORD",
  "callback_code": "ERROR",
  "record": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": {
    "display_message": "The provided credentials were not correct. Please try again.",
    "error_code": "RECORD_LOGIN_REQUIRED",
    "error_message": "the provided credentials were not correct",
    "error_type": "RECORD_ERROR",
    "status": 400
  }
}

Income Callback

If you're using callbacks with the Incomeproduct, you'll receive a callback when Okra calculates the Income data for the Record. Once you receive this callback, you can make an /income/get API request to retrieveIncomedata.

Income ready callback

{
  "callback_type": "INCOME",
  "callback_code": "PDOCUT_IS_READY",
  "record": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null
}

Identity Callback

If you're using callbacks with the Identity product, you'll receive a callback when Okra calculates the Identity data for the Record. Once you receive this callback, you can make an /identity/get API request to retrieve Identity data.

Identity ready callback

{
  "callback_type": "IDENTITY",
  "callback_code": "PRODUCT_IS_READY",
  "record": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null
}

Balance Callback

If you're using callbacks with the Balance product, you'll receive a callback when Okra calculates the Balance data for the Record. Once you receive this callback, you can make an /balance/get API request to retrieve Balancedata.

Balance ready callback

{
  "callback_type": "BALANCE",
  "callback_code": "PRODUCT_IS_READY",
  "record": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null
}