Skip to main content

Web hooks

Clients have possibility to define a callback URL, where they will be notified on some specific event. Please contact our technical support for help with setting a callback URL for your organization.

Authentication​

POST https://{client-defined-authentication-url}

For clients that are using OAuth 2.0 for authentication, it is possible to define authentication parameters: authentication URL, client_id and client_secret that will be used to authenticate to the client's system. Authentication parameters is possible to set using Incode dashboard. In an authentication flow Incode will exchange client_id and client_secret for an access token, that will be used later when sending notifications.

Request:

Headers:

  • Content-Type: application/x-www-form-urlencoded
  • Authorization: Basic base64(client_id:client_secret)

Body:

  • grant_type: String. Always set to: "client_credentials"

Response:

  • access_token: String, mandatory. Access token to be usend when sending notifications.
  • expires_in: Number, mandatory. Access token expiration time in seconds.

Notify onboarding status changed​

POST https://{client-defined-url}

Notify client on onboarding status change.

Request: Headers:

  • Authorization: String, optional. Bearer ACCESS_TOKEN. Only for clients that are using OAuth 2.0 for authentication.

Body:

  • interviewId: String, mandatory. Session ID.
  • externalId: String, optional. External ID - only if it was sent in start.
  • onboardingStatus: String, mandatory. New status for given session. Possible values: UNKNOWN, ID_VALIDATION_FINISHED, POST_PROCESSING_FINISHED, FACE_VALIDATION_FINISHED, GOVERNMENT_VALIDATION_FINISHED,ONBOARDING_FINISHED, MANUAL_REVIEW_APPROVED, MANUAL_REVIEW_REJECTED

Response:

  • success: Boolean. Flag indicating client received notification successfully.

Retry Policy: There's a one time retry that will be triggered in the following scenarios: 1- timeout when calling your endpoint. 2- the response of your service is not status 200 OK with response type application/json or 204 No content.

The retry attempt request will be exactly the same as the initial one.

Notify global watchlist has updates​

POST https://{client-defined-url}

Notify client that global watchlist search has updates. Received ref and search_id have similar usages. Any of the received fields can be used to retrieve the new search result using updated-watchlist-result

Request:

Body:

  • interviewId: String, mandatory. Session ID.
  • ref: String, mandatory. Reference number received when search was created.
  • search_id: String, mandatory. Search id created when search was created.