Callback Integration

Configure a callback URL to automatically receive notifications about the status of each transaction.

You can set a global callback URL in the Application Settings in the Jumio Portal, or override it per request using the callbackUrl as an optional field in the Account creation or update request body, see Creating or Updating Accounts.

Best Practices

• Use callbacks to track workflow processing.
• Save the received callback data and respond with 200 OK to Jumio.
• After receiving callbacks, retrieve transaction details or images using the retrieval APIs, refer Calling Retrieval APIs.

Callback IP Allowlist

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