Callback


The Callback is a service that notifies client services based on document flow, sending the signature status of its running flow. If the client service is unavailable, the callback tries to resend the status for 8 hours with attempts every 2 hours. If there's no success after that, the status is no longer sent and an e-mail is sent to admin registered for the callback.

The signature is an asynchronous task, so the Callback is the recommended way to get document signature status if there are signers out of your environment, i,e, if some signer does not has a login in your system. Otherwise, if all signers are into your system, you could use the JavaScript API which provides the status immediately after the signature has been performed.


Setting the callback


In order to use this resource, it’s necessary that the client has a REST API Service that will be requested by the Callback Service. With an available client service API, the callback must be configured with the service URL and request headers if needed. You must also select the Trigger Type that will fire the callback service.


Callback Configuration Model


These are the fields required for callback configuration.

Name Type Description
trigger string Callback behavior options.
url string Url address for client API service.
headers Header[] Request headers for the client service API.

Trigger


Determines when the callback service will be fired, sending the status to the client service APIs.

Name Type Description
FLOW string The callback will be fired only in the end of the flow (when all signatures have been performed)
STEP string The callback will be fired in the end of each step and also in the end of the flow.
ACTION string The callback will be fired in each action performed, in the end of each step and also in the end of the flow.

Headers


If the client service API requires request headers, the respective names and values ​​must be entered in the callback configuration.

Name Type Description
name string Header name
value string Header value

Receiving callback status data

Sample of callback post request to the client service:

    
    { 
        "documentID": 123456,
        "name": "João da Silva",
        "identifier": "307.625.739-02",
        "action": "SIGNATURE-DIGITAL",
        "message": ""
        "apiDonwload": "https://api-sbx.portaldeassinaturas.com.br/api/v2/document/Package?key=4B4659AB34847973&includeOriginal=false"
    }
    
    

Callback Sender Model


The client service API must be ready to receive the parameters sent by the Callback Service. The parameters are represented by the model below.

Name Type Description
documentId string Document Id
name string The person's name who performed the action (signature, authorization, etc.)
identifier string The person's CPF who performed the action (signature, authorization, etc.)
action Action Possible actions to be send, according to callback behavior configuration

Action


Action details.

Name Type Description
SIGNATURE-ELETRONIC string Electronic signature performed by signer without an digital certificate.
SIGNATURE-DIGITAL string Digital signature performed by signer using an digital certificate.
SIGNATURE-SERVER string Digital signature performed by server using an company digital certificate.
SIGNATURE-NOK string Signature rejected by signer.
AUTHORIZATION-OK string Document authorized by authorizer.
AUTHORIZATION-NOK string Document not authorized by authorizer.
APPROVAL-OK string Document approved by aprover.
APPROVAL-NOK string Document not approved by aprover.
STEP-<step_number> string All signatures performed for the step.
FLOW string Document flow completed. All signatures performed.