How do I set up a callback?

The size of the payload sent to your callback can vary. We recommend your callback should accept payloads up to 1.5MB in size.

The callback mechanism allows for asynchronous job requests and responses. While the job_status API can be polled to get a result, a better method is to set up a callback url and let the system POST a JSON response. This is especially recommended for SDK implementations because the result will go directly back to your server and avoid client side security issues.

Jobs can take different times to process. While most jobs take only a few seconds, jobs that require human review can take longer. The callback mechanism allows you to make a job request and receive all results without polling.

The partner params structure is passed back with every callback. We suggest using the job_id parameter to connect job requests and job results. You can also set optional keys in the partner params structure to aid in this connection.

Setting your callback url

Most of the job requests you submit are processed asynchronously, which means results are not immediately available. We require callbacks so we can post json responses when the results of your job are available. There are two main callback urls you can set for your requests - a default callback which we will post results to by default or you can pass a callback url in each job request you make, in this case responses will be posted to the job level callback.

We require you to set a callback url each for Sandbox and Production.

Setting the Default Callback URL

There are two ways of setting default callback urls:

A. Partner Portal

Setting default Callback URL in Portal

Follow the steps below to set your default callback url in the partner portal

1. Login into the portal

2. Switch to the Developer Tools page from the menu

3. Click Set on the Default Callback URL card

4. Input your callback url (take note of the active environment)

5. Toggle to the other environment and input the url

B. Server to Server Libraries

You can also set default callback in any of our server-to-server libraries, you can achieve this by setting the default_callback parameter in the initialisation of the WebAPI class of the server-to-server library you are using.

Setting the per Job Callback URL

Setting a callback on a job request will override the callback URL for that job only

Setting a job level callback url varies based on your integration option of choice.

A. Rest API

For products that support callback urls, just set your url as string in the callback_url key of your request body.

B. Server to Server Libraries

Set the optional_callback parameter in the options structure passed to the submit_job function of the WebAPI class.

C. Mobile SDKs

You can set the per job callback url in the mobile SDKs by using the method <SIDNetData>.setCallBackUrl(<Your_Callback_URL>).

Whitelisting

To be sure the requests being received are, in fact, from Smile ID there are 2 ways this can be done

1. Verifying the incoming signature parameter in the request body of the result

2. Whitelisting our originating IP addresses (see below):

For Production callbacks:

34.240.137.52

44.230.128.108

52.36.32.43

52.213.46.74

For Sandbox callbacks:

35.166.227.53

44.246.19.66

54.246.37.255

99.81.237.141