Callback

Specify a callback URL (for constraints refer 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. Refer: 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, refer 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	Contains details about the workflow execution.
workflowExecution.id	string	UUID of the workflow
workflowExecution.href	string	URL to retrieve workflow details
workflowExecution.definitionKey	string	Key of the workflow definition that was executed
workflowExecution.status	string	Possible values: PROCESSED: The workflow has been successfully processed. ACQUISITION_STARTED: The user has opened the transaction link, and the acquisition started. Note: This status is only available if enabled. Please contact Jumio Support to activate it. ACQUIRED: The user has completed the required verification steps. Note: This status is only available if enabled. Please contact Jumio Support to activate it. SESSION_EXPIRED: The session expired before the user could complete the workflow. TOKEN_EXPIRED: The access token has expired before the transaction was started.
account	object	Contains account details.
account.id	string	UUID of the account
account.href	string	URL to retrieve account details

Example

{
  "callbackSentAt": "2025-07-28T14:27:46.776Z",
  "userReference": "string",
  "workflowExecution": {
    "id": "2222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "href": "https://retrieval.emea-1.jumio.ai/api/v1/workflow-executions/2222222-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "definitionKey": "10172",
    "status": "PROCESSED"
  },
  "account": {
    "id": "11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "href": "https://retrieval.emea-1.jumio.ai/api/v1/accounts/11111111-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}