Callback

Specify a callback URL (for constraints see Application Settings) to automatically receive notifications about the status of each transaction.

You can specify a global callback URL in the Application Settings in the Jumio Portal. You can also override the default by specifying the callbackUrl as an optional field in the Account creation or update request body. See also: Creating or Updating Accounts.

Best Practices

  • Use callbacks to check if a workflow has finished processing.
  • Once Jumio has sent the callback, save it on your side and send back a 200 OK response.
  • Afterwards, to retrieve transaction details or images, use the retrieval APIs. See Calling Retrieval APIs.

Jumio Callback IP Addresses

Allowlist the following IP addresses and hostnames for callbacks, and use them to verify that the callback originated from Jumio.

US Data Center:

  • 34.202.241.227
  • 34.226.103.119
  • 34.226.254.127
  • 52.8.136.236
  • 54.177.61.57
  • 54.183.15.212

Hostname callback.amer-1.jumio.ai

EU Data Center:

  • 34.253.41.236
  • 35.157.27.193
  • 52.48.0.25
  • 52.57.194.92
  • 52.58.113.86
  • 52.209.180.134

Hostname callback.emea-1.jumio.ai

SGP Data Center:

  • 3.0.109.121
  • 52.76.184.73
  • 52.77.102.92

  • 13.238.100.17

  • 13.238.203.238

  • 52.64.132.26

Hostname callback.apac-1.jumio.ai

Callback Parameters

An HTTP POST request is sent to your specified callback URL containing an application/json formatted string with the transaction status and metadata.

Parameter Type Notes
callbackSentAt string

UTC timestamp of the callback in the format:

YYYY-MM-DDThh:mm:ss.SSSZ
userReference string User reference (if set in initiate call)
workflowExecution object

Possible values:

  • workflowExecution.id

  • workflowExecution.href
workflowExecution.id string UUID of the workflow
workflowExecution.href sting URL to retrieve workflow details
workflowExecution.definitionKey string Key of the workflow definition that was executed.
workflowExecution.status string

Possible values:

  • PROCESSED

  • SESSION_EXPIRED

  • TOKEN_EXPIRED
account object

Possible values:

  • account.id

  • account.href
account.id   UUID of the account
account.href   URL to retrieve account details

Example

Copy 
{
  "callbackSentAt":"2021-01-21T14:55:01.917Z",
  "workflowExecution":{
    "id":"22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "href":"https://retrieval.apac-1.jumio.ai/api/v1/accounts/11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx/workflow-executions/22222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "definitionKey":"3",
    "status":"PROCESSED"
},
  "account":{
    "id":"11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "href":"https://retrieval.apac-1.jumio.ai/api/v1/accounts/11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}