Webhooks

This service notifies you when an identity validation session is being processed or completed.

Digital signature request verification process

We send a set of HTTP headers to authenticate it along with the notification.

The HTTP headers we send are:

  • X-Api-Key : this header allows you to identify which api-secret you have to use in the event that multiple api-key and api-secret pairs have been configured.

  • X-Signature : this header contains the digital signature (timestamp + endpoint + body) that must be verified to ensure the integrity of the request. If the signature does not match, the order must be rejected.

  • X-Timestamp : this header contains the moment the order was signed in unix-epoch format so that you can verify that the signature has not expired.

  • X-Endpoint : the endpoint to which the request is made and used to generate the signature. Use this header to regenerate the signature to be validated, compare it with the endpoint of your service and verify that they match.

The digital signature is an HMAC-SHA256 code constructed using the 'api-secret' and a series of bytes, composed of a timestamp concatenation, endpoint and request body coded in UTF-8.

The following is a pseudo-code to verify that the digital signature of a request is legitimate:

requestSignature = request.headers['x-signature']

signatureData = encode(request.headers['x-timestamp'] + request.headers['x-endpoint'] + request.body , 'UTF-8')

clientApiSecretDecoded = base64.b64decode(apiSecret)

recreatedSignature = hmac(clientApiSecretDecoded, signatureData, 'SHA256')

validSignature = requestSignature == 'hmac-sha256 ' + recreatedSignature

Validation session notifications

You must inform us of this endpoint to receive notifications of an identity validation session. You must return a type 2xx HTTP code so that the notification is not sent again Otherwise, we will send it again.

Available parameters
Header Parameters
X-Api-Keystringrequired
This header helps you identify which api-secret to use if multiple api-key and api-secret pairs were configured.
Example: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
This header contains the digital signature (timestamp + endpoint + body) that must be verified to ensure the integrity of the request. If the signature does not match, the order must be rejected.
Example: X-Signature: hmac-sha256 N70BkBKch1gwQDPj0jF0ooB9QQVXBEp5VQE+SGe6Z0k=
X-Timestampstringrequired
This header has the moment the order was signed in unix-epoch format so that you can verify the signature has not expired.
Example: X-Timestamp: 1637117179
X-Endpointstringrequired
The endpoint where the order is placed and used to create the signature. Use this header to regenerate the signature to be validated, check with your service endpoint and confirm that they match.
Example: X-Endpoint: /client/api/session/completed
Body Parameters
event_idstringrequired
Event identifier.
Example: identity-session-status-changed
Enum: identity-session-status-changed
idempotency_keystringrequired
Idempotent identifier for creating the event.
Example: 27Ky00tAZ0Rdi7G2Vt9iino8AYs
sessionobjectrequired
Identity validation session

Was this section helpful to you?

POST/identity/v1/<session-event-client-url>
{
"event_id":
"identity-session-status-changed"
"idempotency_key":
"27Ky00tAZ0Rdi7G2Vt9iino8AYs"
"session":{
"id":
"iss-27KxRhP9YB4ouoyt6a5vVJlY9fR"
"status":
"VERIFIED"
}
}
Response examples

Notification of required file

Please provide us with this endpoint to receive notifications for required files. You must return us an HTTP code in the 2xx range to prevent us from resending the notification. Otherwise, we will send it again.

Available parameters
Header Parameters
X-Api-Keystringrequired
This header helps you identify which api-secret to use if multiple api-key and api-secret pairs were configured.
Example: X-Api-Key: h3Ws4Cv09JcCdw7732ig+1Eq3I2b+IWOI1anUu1A4dE=
X-Signaturestringrequired
This header contains the digital signature (timestamp + endpoint + body) that must be verified to ensure the integrity of the request. If the signature does not match, the order must be rejected.
Example: X-Signature: hmac-sha256 N70BkBKch1gwQDPj0jF0ooB9QQVXBEp5VQE+SGe6Z0k=
X-Timestampstringrequired
This header has the moment the order was signed in unix-epoch format so that you can verify the signature has not expired.
Example: X-Timestamp: 1637117179
X-Endpointstringrequired
The endpoint where the order is placed and used to create the signature. Use this header to regenerate the signature to be validated, check with your service endpoint and confirm that they match.
Example: X-Endpoint: /client/api/session/completed
Body Parameters
event_idstringrequired
Event identifier.
Example: identity-required-file
Enum: identity-required-file
idempotency_keystringrequired
Idempotent identifier for creating the event.
Example: 27Ky00tAZ0Rdi7G2Vt9iino8AYs
sessionobjectrequired
Identity validation session
actionobjectrequired
Action required

Was this section helpful to you?

POST/identity/v1/<required-file-event-client-url>
{
"event_id":
"identity-required-file"
"idempotency_key":
"27Ky00tAZ0Rdi7G2Vt9iino8AYs"
"session":{
"id":
"iss-27KxRhP9YB4ouoyt6a5vVJlY9fR"
}
"action":{
"file_type":
"company-document"
"reason":
"A legal representation letter is missing"
"requested_at":
"2023-02-09T13:20:32.593Z"
}
}
Response examples