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 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.52.51.178
  • 52.53.95.123
  • 54.67.101.173

Use the hostname callback.jumio.com to look up the most current IP addresses.

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

Use the hostname callback.lon.jumio.com to look up the most current IP addresses.

SGP Data Center:

  • 3.0.109.121
  • 52.76.184.73
  • 52.77.102.92

Use the hostname callback.core-sgp.jumio.com to look up the most current IP addresses.

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"
  }
}