Webhooks notify the BU when something changes in an account, a document, a registration or a request. They are the recommended way to track processing, because the synchronous API response only confirms that the request was received. This page lists the webhooks and what the BU must do when it receives each one. Because webhooks are not yet described in the API Reference, the main fields of each event are on this page.

Available webhooks

WebhookWhen it arrivesWhat the BU must do
Account webhook (UpdateAccount)When there is an event in the account, such as a change of condition.Update the account condition in the BU system and prevent early release.
Documents webhook (UpdatePersonDocument)When there is an event or a pending item in a document, including a signer's document.Direct the resubmission or completion of the document.
UpdatePersonConditionWhen there is a correction, a block or a restriction in the registration of the person, and with the result of the KYC and AML analysis.Query the data and apply the indicated method.
UpdatePersonInfoWhen the data change request (ChangePersonInfo) has a result.Follow it by the USN of the request.
UpdateCloseAccountWhen the closing request has a result.Consider the account closed only after the final status.
Signer inclusion webhook (FBWebhookWorkerUpdateSignerSolicitation)When a signer inclusion request is generated, approved or rejected.Update the signer link only after the final result.
UpdatePersonContractWhen the digital contract of a company account is sent for signature (2 Sent), signed (3 Signed), refused (6 NotSigned) or expires (8 Expired). The other statuses do not generate a notice. The contract exists when the company NewAccount sends Contract.ContractModel equal to 1 (DigitalSignature). It only reaches BUs that have the webhook enabled by Fits and the URL registered.Follow the signature by the ContractStatus and consider the contract signed only with status 3 (Signed).
Limit change webhook (AccountOperationLimitChangeWebhook)After the analyst decides on a limit change request (approved, partially approved or denied). A change applied immediately does not generate this notice.Follow the decision on the account limit.

The meaning of each status and classification value that these webhooks return is in Code Mapping. For the account condition, see Account Status. For the document statuses, see Pending Documents.

Fields of each webhook

The fields below apply to the account webhook, the documents webhook (including the signer document), UpdatePersonCondition, UpdatePersonInfo, UpdateCloseAccount, the signer inclusion webhook, the limit change webhook and UpdatePersonContract. The values in the examples are fictitious.

Account webhook

Notifies the BU when the account condition changes. The Method field comes with the value UpdateAccount.

FieldDescriptionTypeValues
PartnerIdIdentifier provided by FitsNumber
BusinessUnitIdIdentifier of the BU, provided by FitsNumber
TaxNumberCPF or CNPJ of the end customerText
NameName of the account holderText
CreationDateAccount creation dateDate and time
AccountStatusIndicates whether the account is activeNumberThe values of AccountStatus are listed in the Code Mapping, in the section Account status.
AccountConditionTypeAccount conditionNumberThe values of AccountConditionType are listed in the Code Mapping, in the section Account condition.
Bank, BankBranch, BankAccount and BankAccountDigitInternal bank data of the account, which are not SPB dataText
AccountKeyUnique account identifierTextIt comes empty when the account has no key yet.
SendDateDate and time the webhook was sentDate and time
SpbAccountSPB account data (Bank, BankBranch, BankAccount and BankAccountDigit)ObjectOnly sent when the TaxNumber has one or more SPB accounts; otherwise it is null.
MethodWebhook nameTextUpdateAccount

The webhook is created when an account is opened (CreateAccount, NewAccount, LimitedAccount and CompanyLimitedAccount), when registration data is updated (UpdatePersonData) and with the result of the KYC analysis.

The BlockAccount and UnlockAccount methods do not generate this webhook. The condition 3 (Blocked) reaches the BU only when the block comes from the KYC analysis.

Closing an account does not generate the UpdateAccount webhook. To track a closing, use UpdateCloseAccount, described below.

Example of an account with an SPB account:

{
  "Method": "UpdateAccount",
  "PartnerId": 100,
  "BusinessUnitId": 200,
  "TaxNumber": "11122233344",
  "Name": "MARIA DE EXEMPLO",
  "CreationDate": "2026-01-10T14:11:42.68",
  "SendDate": "2026-01-11T15:02:00-03:00",
  "AccountStatus": 1,
  "AccountConditionType": 2,
  "AccountKey": "000000-000000-0000000-0",
  "Bank": null,
  "BankBranch": null,
  "BankAccount": null,
  "BankAccountDigit": null,
  "SpbAccount": {
    "Bank": "450",
    "BankBranch": "0001",
    "BankAccount": "00011223",
    "BankAccountDigit": "2"
  }
}

Example of an account without an SPB account:

{
  "Method": "UpdateAccount",
  "PartnerId": 100,
  "BusinessUnitId": 200,
  "TaxNumber": "11122233344",
  "Name": "MARIA DE EXEMPLO",
  "CreationDate": "2026-01-10T08:35:31.06",
  "SendDate": "2026-01-10T09:00:00-03:00",
  "AccountStatus": 1,
  "AccountConditionType": 0,
  "AccountKey": "000000-000000-0000000-0",
  "Bank": "001",
  "BankBranch": "2812",
  "BankAccount": "2964327",
  "BankAccountDigit": "2",
  "SpbAccount": null
}

Documents webhook

Notifies the BU about the status of each document sent. The Method field comes with the value UpdatePersonDocument. The documents of an account signer also arrive through this webhook.

The webhook is sent in two formats, depending on the flow that creates it:

FlowStructureHas pending item (PendingReason and Message)?
Document analysis in the KYC flowAccount + Document (no Holder)Yes, when the document has a pending item.
Resend of documents (ResendDocuments)Holder + Document (no Account)No. They always come empty.

In the Holder format, Holder.TaxNumber is the CPF or CNPJ of who sent the document.

Fields common to both formats:

FieldDescriptionTypeValues
MethodWebhook nameTextUpdatePersonDocument
BusinessUnitIdIdentifier of the BU, provided by FitsNumber
Document.TaxNumberCPF or CNPJ of who sent the documentText
Document.FileNameName of the file sent through the APIText
Document.DescriptionDocument descriptionText
Document.ExtensionFile extensionText
Document.ExpirationDateDocument expiration dateDate and time
Document.DocumentStatusDocument statusNumberThe values of DocumentStatus are listed in the Code Mapping, in the section Document status.
Document.DocumentTypeDocument typeNumberThe values of DocumentType are listed in the Code Mapping, in the section Document type.
Document.DocumentKeyUnique document identifier. It may come empty.Text
Document.ReasonRejection reason registered for the document, when there is one. It may come empty.Text
Document.UrlDocumentURL to download the document, when availableText
Document.PendingReasonReason for the pending item, when there is oneNumberSee the table below.
Document.MessageMessage about the pending item, in Portuguese, to show to the end customerText

Fields of the Account format (KYC flow): Account.AccountStatus, Account.AccountConditionType, Account.TaxNumber, Account.Bank, Account.BankBranch, Account.BankAccount, Account.BankAccountDigit and Account.AccountKey.

Field of the Holder format (resend of documents): Holder.TaxNumber.

Example of the Holder format:

{
  "Method": "UpdatePersonDocument",
  "BusinessUnitId": 200,
  "Holder": {
    "TaxNumber": "11122233344"
  },
  "Document": {
    "TaxNumber": "11122233344",
    "FileName": "cnh_back.jpeg",
    "Description": "CNH back",
    "Extension": ".jpeg",
    "ExpirationDate": null,
    "DocumentStatus": 1,
    "DocumentType": 16,
    "DocumentKey": "",
    "Reason": "",
    "PendingReason": null,
    "Message": ""
  }
}

Example of the Account format with a pending item:

{
  "BusinessUnitId": 200,
  "Method": "UpdatePersonDocument",
  "Account": {
    "AccountStatus": 1,
    "AccountConditionType": 0,
    "TaxNumber": "11122233344",
    "Bank": "001",
    "BankBranch": "2812",
    "BankAccount": "2964327",
    "BankAccountDigit": "2",
    "AccountKey": "000000-000000-0000000-0"
  },
  "Document": {
    "FileName": "selfie.jpeg",
    "Description": "Selfie",
    "Extension": ".jpeg",
    "ExpirationDate": null,
    "DocumentStatus": 2,
    "DocumentType": 17,
    "DocumentKey": "",
    "Reason": "",
    "TaxNumber": "11122233344",
    "PendingReason": 3,
    "Message": "A imagem da selfie enviada está ilegível. Para prosseguir com a abertura da conta, por favor, reenvie uma foto clara e legível."
  }
}

When a document has a pending item, the webhook carries PendingReason and Message, so the BU can guide the end customer:

PendingReasonMeaningMessage (in Portuguese)What the BU must do
0 (IllegibleDocument)The document sent is illegible for validation.A documentação repassada está ilegível. Por favor, reenvie os documentos de identificação pessoal para prosseguir com a abertura da conta.Ask the end customer to resend the identification documents.
1 (ErasedDocument)The document has erasures.This value is sent with an empty message.Ask the end customer to send a valid document without erasures.
2 (InvalidDocumentation)The document sent is not what was requested, for example when it is neither RG nor CNH.A documentação de identificação fornecida não corresponde à solicitada. Por favor, envie apenas uma identificação válida, como o Registro Geral (RG) ou a Carteira Nacional de Habilitação (CNH).Ask the end customer to send only a valid identification document, RG or CNH.
3 (IllegibleSelfie)The selfie sent is illegible.A imagem da selfie enviada está ilegível. Para prosseguir com a abertura da conta, por favor, reenvie uma foto clara e legível.Ask the end customer to send a new selfie.

The Reason field carries only the rejection reason registered for the document. The pending situations above come in PendingReason and Message.

UpdatePersonCondition

Notifies the BU of the result of the KYC and AML analysis of a person, and when there is a correction, a block or a restriction in the registration. The Method field comes with the value UpdatePersonCondition.

FieldDescriptionTypeValues
PartnerIdIdentifier provided by FitsNumber
BusinessUnitIdIdentifier of the BU, provided by FitsNumber
TaxNumberCPF or CNPJ of the end customer, as registeredText
AccountsKeyIdentifiers of the accounts, separated by commaTextFor a signer it comes null.
MessageMessage about the situation of the person, in PortugueseText
MessageClassificationFinal situation of the person in the analysisNumberThe values of MessageClassification are listed in the Code Mapping, in the section KYC analysis classification. The meaning of each one is in the table below. It does not come in the notice of person created ("Pessoa criada com sucesso"), which has no classification.
MethodWebhook nameTextUpdatePersonCondition

The webhook does not list the fields with divergent data: the BU receives the classification and the message.

The MessageClassification field identifies which situation the person is in within the KYC analysis:

ValueStatusMessage (example, in Portuguese)Meaning and what to do
0DivergentInformationPrezado(a) Cliente, foi constatada uma divergência nos dados enviados para a abertura de conta. Solicitamos, por gentileza, que encaminhe novamente as informações com as correções necessárias. Agradecemos sua compreensão.The end customer sent inconsistent data at the opening. The BU must correct it with the ChangePersonInfo method.
1DisapprovedFor a BC Protege+ restriction: Negado por restrição no BC Protege+. Oriente o usuário a rever o(s) CPF/CNPJ: {CPF/CNPJ} e somente envie uma nova solicitação após revisão. For the other reasons: Prezado(a) Cliente, após validações internas, não foi possível seguir com a abertura da conta. Agradecemos sua compreensão.The end customer did not pass the KYC and AML analysis and cannot proceed with the opening. See BC Protege+.
2InternalDisapprovedPrezado(a) Cliente, devido as politicas internas da empresa, não foi possível seguir com a abertura da conta. Pedimos que aguarde um prazo de 72 horas para uma nova tentativa. Agradecemos sua compreensão.The end customer does not meet the internal risk guidelines at this moment (documents or selfie disapproved). They can try to open the account again after 72 hours.
3ExpiredDocumentPrezado Cliente, Sua solicitação de abertura de conta expirou por falta da documentação necessária. Para continuar, por favor, refaça sua solicitação. Você pode fazer uma nova solicitação após 72 horas. Agradecemos pela compreensão.The end customer did not go through KYC because the documentation was rejected, and cannot proceed with the opening. They can try again after 72 hours.
4ClientApprovedCliente aprovadoThe end customer was approved.

What the BU does for each MessageClassification value:

flowchart TD
  A["UpdatePersonCondition webhook"] --> B{"MessageClassification"}
  B -->|"0 DivergentInformation"| C["BU corrects with ChangePersonInfo"]
  B -->|"1 Disapproved, includes Protege+"| D["Opening does not proceed"]
  B -->|"2 InternalDisapproved"| E["New attempt after 72 hours"]
  B -->|"3 ExpiredDocument"| E
  B -->|"4 ClientApproved"| F["Customer approved"]

Example with divergent information:

{
  "Method": "UpdatePersonCondition",
  "PartnerId": 100,
  "BusinessUnitId": 200,
  "TaxNumber": "11122233344",
  "Message": "Prezado(a) Cliente, foi constatada uma divergência nos dados enviados para a abertura de conta. Solicitamos, por gentileza, que encaminhe novamente as informações com as correções necessárias. Agradecemos sua compreensão.",
  "MessageClassification": 0,
  "AccountsKey": "000000-000000-0000000-0"
}

Example of an approved end customer:

{
  "Method": "UpdatePersonCondition",
  "PartnerId": 100,
  "BusinessUnitId": 200,
  "TaxNumber": "11122233344",
  "Message": "Cliente aprovado",
  "MessageClassification": 4,
  "AccountsKey": "000000-000000-0000000-0,000000-000000-0000000-1"
}

UpdatePersonInfo

Notifies the BU of the result of ChangePersonInfo and carries the USN of the request. The Method field comes with the value UpdatePersonInfo, and the Status field carries one of three messages, sent in Portuguese:

Message (Status)MeaningWhat the BU must do
Sua solicitação foi criada ("Your request was created")The request was received and registered.Wait for the result.
Sua solicitação foi aprovada ("Your request was approved")The change was approved.Update the data in the BU system only with the PersonInfos items whose Status is Approved.
Sua solicitação foi rejeitada ("Your request was rejected")The change was not applied.Keep the current data, evaluate the reason and guide the end customer.

The path of a data change, from ChangePersonInfo to the result:

flowchart TD
  A["BU sends ChangePersonInfo"] --> B["Fits generates the USN"]
  B --> C["Webhook: request created"]
  C --> D{"Result"}
  D -->|"Approved"| E["BU updates only the items with Status Approved"]
  D -->|"Rejected"| F["BU keeps the current data"]

UpdatePersonInfo fields:

FieldDescriptionType
MethodWebhook name. Fixed value: UpdatePersonInfoText
BusinessUnitIdIdentifier of the BU, provided by FitsNumber
TaxNumberCPF or CNPJ of the person whose data is being changedText
StatusMessage about the status of the request, as in the table aboveText
USNIdentifier of the request, equal to the USNId returned by ChangePersonInfoText
PersonInfosData included in the change requestList
PersonInfos[].PersonInfoTypeName of the changed data, such as Email or PhoneNumberText
PersonInfos[].StatusStatus of the item, sent as the name of the status: Created, Approved, Rejected, ApprovedJD or DisapprovedJD (the same names as in GetChangeInfo). A request whose items are all Rejected or DisapprovedJD is notified as rejected; otherwise it is notified as approved, so the BU must update the data only for the items that were approved.Text
PersonInfos[].PersonInfoValueNew value requested for the dataText

Example:

{
  "Method": "UpdatePersonInfo",
  "BusinessUnitId": 200,
  "TaxNumber": "11122233344",
  "Status": "Sua solicitação foi aprovada",
  "USN": "3f2b8e4a-9c1d-4e7a-b2f6-8d5a1c7e9b34",
  "PersonInfos": [
    {
      "PersonInfoType": "Email",
      "Status": "Approved",
      "PersonInfoValue": "[email protected]"
    },
    {
      "PersonInfoType": "PhoneNumber",
      "Status": "Approved",
      "PersonInfoValue": "11999990000"
    }
  ]
}

The registration correction flow is in Updating Registration Data.

UpdateCloseAccount

Notifies the BU of the progress of the closing request. The Method field comes with the value UpdateCloseAccount, and the status values are in the table below.

FieldDescriptionType
BusinessUnitIdIdentifier of the BU, provided by FitsNumber
AccountKeyUnique account identifier. It comes empty when the account has no keyText
CloseAccountInformationStatusStatus of the request at that momentNumber
MessageMessage that informs the end customer of the status of the request, in PortugueseText
URLCloseAccountLink to the closing document. Only sent when the status is 5 (Approved)Text
Bank, BankBranch, BankAccount and BankAccountDigitInternal bank data of the accountText
MethodWebhook name. Fixed value: UpdateCloseAccountText

The values of CloseAccountInformationStatus are listed in the Code Mapping, in the section Closing status. The meaning of each one and what the BU must do:

ValueStatusMessageMeaning and what the BU must do
0CreatedSolicitação em análiseThe request was registered. The BU must wait for the next statuses.
1ProcessingName of the statusThe closing is in progress. The BU must wait.
2ErrorName of the statusThere was a failure in processing or there is a condition that prevents the closing. The BU must resolve the condition or contact Fits support, and must not consider the account closed.
3PendingDescription of the pending itemThe request is pending. The BU must wait for the next statuses.
4DisapprovedSolicitação de cancelamento reprovadaClosing request disapproved.
5ApprovedConta cancelada com sucessoThe account was closed. It is the only status in which the BU must consider the account closed.
6AutomaticClosingRequestPrezado(a) Cliente, informamos que foi iniciado o processo de encerramento automático de sua conta por motivos internos. Pedimos que tente realizar uma nova solicitação de abertura de conta dentro de 72 horas. Agradecemos sua compreensão.An automatic closing request. The BU must wait for the next statuses.

Not all of these values generate a notification. The closing of Locker accounts and a closing made directly by Fits do not generate UpdateCloseAccount.

Example with status 5:

{
  "BusinessUnitId": 200,
  "Method": "UpdateCloseAccount",
  "CloseAccountInformationStatus": 5,
  "Message": "Conta cancelada com sucesso",
  "URLCloseAccount": "https://exemplo.fits.com.br/encerramento/123",
  "Bank": "001",
  "BankAccount": "2964327",
  "BankBranch": "2812",
  "BankAccountDigit": "2",
  "AccountKey": "000000-000000-0000000-0"
}

Signer inclusion webhook

Notifies the BU of the status of a signer inclusion request: Gerada (generated), Aprovado (approved) or Reprovado (disapproved). The Method field comes with the value FBWebhookWorkerUpdateSignerSolicitation. The BU only updates the signer link after the final return. The flow is in Adding Signers.

Status (SignerSolicitationStatus)MeaningWhat the BU must do
GeradaThe inclusion request was received and will be analyzed.Wait for the analysis. This notice is not sent in every case.
AprovadoThe inclusion of the signer was approved.Update the signer link in the BU system.
ReprovadoThe inclusion was not approved.Do not link the signer and evaluate the cause with GetRequestSigner.

The manual removal of a signer does not generate this webhook.

The statuses Sob análise interna, Reprovado (KYC), Pendente de Documentos and Erro do not generate this webhook. The notice "Gerada" is sent only when the KYC analysis of the request is still pending at the moment of the request; if the analysis is already approved, the request goes to internal review, and if it is already disapproved, the request is rejected, in both cases without this notice. Aprovado and Reprovado are sent when the analyst decides on the request.

Webhook fields:

FieldDescriptionType
MethodWebhook name. Fixed value: FBWebhookWorkerUpdateSignerSolicitationText
BusinessUnitIdIdentifier of the BU, provided by FitsNumber
SignerSolicitationStatusStatus of the request. The values of SignerSolicitationStatus are listed in the Code Mapping, in the section Signer request status.Text
DescriptionMessage that corresponds to the status of the request, in PortugueseText
USNIdentifier of the inclusion requestText
HolderPersonAccount holder (name of the company)Text
SignerPersonSigner (name of the person)Text
RequestDateDate of the request, in the format used by the server; there is no guarantee of ISO 8601Text

Example with the request generated:

{
  "BusinessUnitId": 200,
  "Method": "FBWebhookWorkerUpdateSignerSolicitation",
  "SignerSolicitationStatus": "Gerada",
  "Description": "Agradecemos por sua solicitação, que será submetida a uma análise cuidadosa. Por favor, esteja ciente de que esse processo pode levar alguns dias. Assim que a análise for concluída, entraremos em contato com você.",
  "USN": "3f2b8e4a-9c1d-4e7a-b2f6-8d5a1c7e9b34",
  "HolderPerson": "EMPRESA EXEMPLO LTDA",
  "SignerPerson": "MARIA DE EXEMPLO",
  "RequestDate": "26/10/2026 14:03:11"
}

Example with the request approved:

{
  "BusinessUnitId": 200,
  "Method": "FBWebhookWorkerUpdateSignerSolicitation",
  "SignerSolicitationStatus": "Aprovado",
  "Description": "A solicitação para adicionar um novo signatário à conta de EMPRESA EXEMPLO LTDA foi aprovada. Parabéns, você agora é reconhecido como Associado nesta conta.",
  "USN": "3f2b8e4a-9c1d-4e7a-b2f6-8d5a1c7e9b34",
  "HolderPerson": "EMPRESA EXEMPLO LTDA",
  "SignerPerson": "MARIA DE EXEMPLO",
  "RequestDate": "26/10/2026 14:03:11"
}

Example with the request disapproved:

{
  "BusinessUnitId": 200,
  "Method": "FBWebhookWorkerUpdateSignerSolicitation",
  "SignerSolicitationStatus": "Reprovado",
  "Description": "Infelizmente, devido a avaliações internas, não podemos prosseguir com a adição de MARIA DE EXEMPLO à conta de EMPRESA EXEMPLO LTDA neste momento.",
  "USN": "3f2b8e4a-9c1d-4e7a-b2f6-8d5a1c7e9b34",
  "HolderPerson": "EMPRESA EXEMPLO LTDA",
  "SignerPerson": "MARIA DE EXEMPLO",
  "RequestDate": "26/10/2026 14:03:11"
}

Limit change webhook

Notifies the BU after the analyst decides on a limit change request. The Method field comes with the value AccountOperationLimitChangeWebhook. A change applied immediately does not generate this notice. It is sent only to BUs that have the webhook enabled and a URL registered.

This webhook carries only the fields below. It does not include the TaxNumber, the account data or the type of the limit.

FieldDescriptionType
MethodWebhook name. Fixed value: AccountOperationLimitChangeWebhookText
BusinessUnitIdIdentifier of the BU, provided by FitsNumber
StatusDecision on the request: Approved, PartiallyApproved or DeniedText
NewMaxValueMaximum value approved for the limit. It does not come when the request is denied.Number
MessageMessage about the decision, in Portuguese. Approved or partially approved: "A solicitação foi aprovada e o limite foi ajustado com sucesso." Denied: "A solicitação foi reprovada e o limite atual foi mantido."Text

Example (approved):

{
  "BusinessUnitId": 200,
  "Method": "AccountOperationLimitChangeWebhook",
  "Message": "A solicitação foi aprovada e o limite foi ajustado com sucesso.",
  "Status": "Approved",
  "NewMaxValue": 5000
}

Example (denied):

{
  "BusinessUnitId": 200,
  "Method": "AccountOperationLimitChangeWebhook",
  "Message": "A solicitação foi reprovada e o limite atual foi mantido.",
  "Status": "Denied"
}

UpdatePersonContract

Notifies the BU when the digital contract of a company account changes its status. The Method field comes with the value UpdatePersonContract. The contract exists when the account is opened with the company NewAccount and Contract.ContractModel equal to 1 (DigitalSignature): the buyer receives the document by email and signs it electronically. The webhook is only sent to BUs that have it enabled by Fits and the URL registered. The BU must follow the signature by the ContractStatus and consider the contract signed only after status 3 (Signed).

Fields of UpdatePersonContract:

FieldDescriptionType
MethodWebhook name. Fixed value: UpdatePersonContractText
BusinessUnitIdIdentifier of the BU, provided by FitsNumber
ContractIdentifierUnique identifier of the contract (a GUID). Use it to relate the notices of the same contract.Text
HolderTaxNumberCNPJ of the account holder (the company)Text
TaxNumberCPF of the buyer, who signs the contractText
ContractTypeType of the contract. The values are in the Code Mapping, section Contract type.Number
ContractStatusStatus of the contract at that moment. The values are in the Code Mapping, section Contract status, and the ones that generate a notice are in the table below.Number
AccountInternal bank data of the account, which are not SPB dataObject
Account.BankBankText
Account.BankBranchBranchText
Account.BankAccountAccountText
Account.BankAccountDigitAccount check digitText

The webhook is sent only with the statuses below:

ContractStatusMeaningWhat the BU must do
2 (Sent)The document was sent to the buyer to be signed.Wait for the signature.
3 (Signed)The buyer signed the contract.Consider the contract signed.
6 (NotSigned)The buyer refused the document.Evaluate the cause with the end customer.
8 (Expired)The signature period ended without the signature.Guide the end customer on how to proceed.

The other statuses of the contract do not generate this webhook. The path of the contract, from the account opening to the signature result:

flowchart TD
  A["Company NewAccount with ContractModel 1 (DigitalSignature)"] --> B["WaitingKYC"]
  B -->|"KYC approves the account"| C["Created"]
  C --> D["Generated"]
  D --> E["Sent, notice to the BU"]
  E --> F{"Signature result"}
  F -->|"Buyer signs"| G["Signed, notice to the BU"]
  F -->|"Buyer refuses"| H["NotSigned, notice to the BU"]
  F -->|"Period ends without signature"| I["Expired, notice to the BU"]

Example (contract sent for signature, status 2):

{
  "BusinessUnitId": 200,
  "Method": "UpdatePersonContract",
  "ContractIdentifier": "3f2b8e4a-9c1d-4e7a-b2f6-8d5a1c7e9b34",
  "HolderTaxNumber": "11222333000181",
  "TaxNumber": "11122233344",
  "ContractStatus": 2,
  "ContractType": 3,
  "Account": {
    "Bank": "001",
    "BankBranch": "2812",
    "BankAccount": "2964327",
    "BankAccountDigit": "2"
  }
}

Example (contract signed, status 3):

{
  "BusinessUnitId": 200,
  "Method": "UpdatePersonContract",
  "ContractIdentifier": "3f2b8e4a-9c1d-4e7a-b2f6-8d5a1c7e9b34",
  "HolderTaxNumber": "11222333000181",
  "TaxNumber": "11122233344",
  "ContractStatus": 3,
  "ContractType": 3,
  "Account": {
    "Bank": "001",
    "BankBranch": "2812",
    "BankAccount": "2964327",
    "BankAccountDigit": "2"
  }
}

Statuses 8 (Expired) and 6 (NotSigned) use the same body, with the corresponding ContractStatus. The webhook does not bring the PartnerId, the name of the buyer, the link to the document or a text message.

Security, delivery attempts and idempotency

This section applies to the onboarding and account webhooks.

TopicHow it works
AuthenticationAuthentication uses credentials agreed with Fits: Basic authentication, an apikey header or Bearer (token obtained by OAuth 2.0 client credentials). mTLS is optional and depends on configuration. Authentication and signature follow the Authentication and Authentication mTLS pages.
Address (URL)Fits registers the URL of each webhook type.
Delivery attemptsIn the standard delivery, there are 3 sends in total, 1 minute apart. The number of sends and the interval can be adjusted per BU.
Response time (timeout)30 seconds.
When the attempts run outThe event must be resent manually.
Expected responseHTTP 2xx with the body {"Success":true,"Message":"ok"}. The value of Message is not checked. An empty body, a body that is not a JSON or "Success": false counts as a failure, and the webhook is sent again.
IdempotencyThere is no universal idempotency key. The BU must handle duplicated and out-of-order events.

Store each event when you receive it and respond with HTTP 2xx.

How Fits delivers each webhook and what happens when the attempts run out:

flowchart TD
  A["Fits sends the webhook"] --> B{"BU answered HTTP 2xx with a JSON body with Success true within 30 s?"}
  B -->|Yes| C["Delivery completed"]
  B -->|No| D{"Sends left? Default: 3 in total"}
  D -->|"Yes, after 1 minute"| A
  D -->|No| E["Manual resend of the event"]

How to handle webhooks

  1. Handle each webhook idempotently, because the same event may arrive more than once.
  2. Store the USN of the request and relate it to the original request, together with the TaxNumber, the account, the method, the payload, the response and the following events.
  3. Update your system only with the final result of each request.
  4. Reconcile periodically the requests that stayed without a final result, by querying the account or the corresponding tracking method.
  5. Release the end customer journey only after the approval.

Did this page help you?