Event Notifications

Webhooks

Smile uses webhooks to notify your application in real time when an event happens in our servers that is related to your environment.

Event notifications can be sent when a new user is created, an account is successfully connected, an employment document is uploaded, an invitation is sent, or when new any new type data is added such as a user's identity, income, employment, and others. Check out the list of available events that you can subscribe to in our Webhooks reference page.

These are sent via a secure channel, using HTTPS from a static IP address, with the data being sent in JSON format. These also come with a signature for you to validate the authenticity of the payload.

📘

Note

Our static IP address is 18.142.61.230. You can whitelist this IP address in your back-end to ensure that your application receives event notifications coming from Smile.

Webhooks are particularly useful for getting notifications about asynchronous events, and either executing actions in your backend system when any of these events happen, or knowing when to refresh your front-end system to display any new data.

For detailed implementation steps, visit our Webhooks reference page for more information.

Callbacks

Smile also uses callbacks to notify your application in real time of frontend-related events that happen in your environment.

Via callbacks, you can react or perform other actions once your user performs a supported action using the Wink Widget. Listening to events such as account connection, token expiry, or closing of the widget can help your native application manage and react to your user's actions.

List of Callbacks

Example Events

onAccountCreated

Fired when the account linking process has been initiated by the user such as through sending their login credentials. This does not surface the user's login credentials.

onAccountCreated: ({
    accountId,
    userId,
    providerId
}) => {
    console.log('Account created: ', accountId, ' User ID:', userId, ' Provider ID:', providerId)
},

onAccountConnected

Fired when the account linking process has completed successfully, and the user is shown the success connection screen.

onAccountConnected: ({
    accountId,
    userId,
    providerId
}) => {
    console.log('Account connected: ', accountId, ' User ID:', userId, ' Provider ID:', providerId)
},

onAccountRemoved

Fired when the account access has been revoked by the user.

onAccountRemoved: ({
    accountId,
    userId,
    providerId
}) => {
    console.log('Account removed: ', accountId, ' User ID:', userId, ' Provider ID:', providerId)
},

onTokenExpired

Fired when the Link token has expired. You may then call the Refresh Token API to refresh the user's token.

onTokenExpired: () => {
    console.log('Token expired');
},

onClose

Fired when the Wink Widget has been closed by the user via the close icon or exit buttons.

onClose: () => {
    console.log('Widget closed')
},

onAccountError

Fired when the user account linking results in an error. The full list of errors can be seen at the Get Account API reference.

onAccountError: ({
    accountId,
    userId,
    providerId,
    errorCode
}) => {
    console.log('Account error: ', accountId, ' User ID:', userId, ' Provider ID:', providerId, 'Error Code:', errorCode)
},

onUploadsCreated

Fired when the user has submitted documents to be uploaded via the Wink Widget.

onUploadsCreated: ({ uploads, userId }) => {
    console.log('Uploads: ', uploads, ' User ID:', userId);
},

onUploadsRemoved

Fired when the user has removed/revoked uploaded documents via the Wink Widget.

onUploadsRemoved: ({ uploads, userId }) => {
    console.log('Uploads: ', uploads, ' User ID:', userId);
},

onUIEvent

Fired whenever a new widget screen is shown to the user.

onUIEvent: ({ eventName, eventTime, mode, userId, account, archive }) => {
    console.log('Event Name: ', eventName, ', Event Time: ', eventTime, ', mode: ', mode, ', User ID: ', userId, ', Account: ', account, ', Archive: ', archive);
},

For the list of event names, see the table below: