Webhooks
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
| Webhook | When it arrives | What 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. |
| UpdatePersonCondition | When 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. |
| UpdatePersonInfo | When the data change request (ChangePersonInfo) has a result. | Follow it by the USN of the request. |
| UpdateCloseAccount | When 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. |
| UpdatePersonContract | When 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.
| Field | Description | Type | Values |
|---|---|---|---|
| PartnerId | Identifier provided by Fits | Number | |
| BusinessUnitId | Identifier of the BU, provided by Fits | Number | |
| TaxNumber | CPF or CNPJ of the end customer | Text | |
| Name | Name of the account holder | Text | |
| CreationDate | Account creation date | Date and time | |
| AccountStatus | Indicates whether the account is active | Number | The values of AccountStatus are listed in the Code Mapping, in the section Account status. |
| AccountConditionType | Account condition | Number | The values of AccountConditionType are listed in the Code Mapping, in the section Account condition. |
| Bank, BankBranch, BankAccount and BankAccountDigit | Internal bank data of the account, which are not SPB data | Text | |
| AccountKey | Unique account identifier | Text | It comes empty when the account has no key yet. |
| SendDate | Date and time the webhook was sent | Date and time | |
| SpbAccount | SPB account data (Bank, BankBranch, BankAccount and BankAccountDigit) | Object | Only sent when the TaxNumber has one or more SPB accounts; otherwise it is null. |
| Method | Webhook name | Text | UpdateAccount |
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:
| Flow | Structure | Has pending item (PendingReason and Message)? |
|---|---|---|
| Document analysis in the KYC flow | Account + 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:
| Field | Description | Type | Values |
|---|---|---|---|
| Method | Webhook name | Text | UpdatePersonDocument |
| BusinessUnitId | Identifier of the BU, provided by Fits | Number | |
| Document.TaxNumber | CPF or CNPJ of who sent the document | Text | |
| Document.FileName | Name of the file sent through the API | Text | |
| Document.Description | Document description | Text | |
| Document.Extension | File extension | Text | |
| Document.ExpirationDate | Document expiration date | Date and time | |
| Document.DocumentStatus | Document status | Number | The values of DocumentStatus are listed in the Code Mapping, in the section Document status. |
| Document.DocumentType | Document type | Number | The values of DocumentType are listed in the Code Mapping, in the section Document type. |
| Document.DocumentKey | Unique document identifier. It may come empty. | Text | |
| Document.Reason | Rejection reason registered for the document, when there is one. It may come empty. | Text | |
| Document.UrlDocument | URL to download the document, when available | Text | |
| Document.PendingReason | Reason for the pending item, when there is one | Number | See the table below. |
| Document.Message | Message about the pending item, in Portuguese, to show to the end customer | Text |
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:
| PendingReason | Meaning | Message (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.
| Field | Description | Type | Values |
|---|---|---|---|
| PartnerId | Identifier provided by Fits | Number | |
| BusinessUnitId | Identifier of the BU, provided by Fits | Number | |
| TaxNumber | CPF or CNPJ of the end customer, as registered | Text | |
| AccountsKey | Identifiers of the accounts, separated by comma | Text | For a signer it comes null. |
| Message | Message about the situation of the person, in Portuguese | Text | |
| MessageClassification | Final situation of the person in the analysis | Number | The 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. |
| Method | Webhook name | Text | UpdatePersonCondition |
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:
| Value | Status | Message (example, in Portuguese) | Meaning and what to do |
|---|---|---|---|
| 0 | DivergentInformation | 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. | The end customer sent inconsistent data at the opening. The BU must correct it with the ChangePersonInfo method. |
| 1 | Disapproved | For 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+. |
| 2 | InternalDisapproved | Prezado(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. |
| 3 | ExpiredDocument | Prezado 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. |
| 4 | ClientApproved | Cliente aprovado | The 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) | Meaning | What 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:
| Field | Description | Type |
|---|---|---|
| Method | Webhook name. Fixed value: UpdatePersonInfo | Text |
| BusinessUnitId | Identifier of the BU, provided by Fits | Number |
| TaxNumber | CPF or CNPJ of the person whose data is being changed | Text |
| Status | Message about the status of the request, as in the table above | Text |
| USN | Identifier of the request, equal to the USNId returned by ChangePersonInfo | Text |
| PersonInfos | Data included in the change request | List |
| PersonInfos[].PersonInfoType | Name of the changed data, such as Email or PhoneNumber | Text |
| PersonInfos[].Status | Status 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[].PersonInfoValue | New value requested for the data | Text |
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.
| Field | Description | Type |
|---|---|---|
| BusinessUnitId | Identifier of the BU, provided by Fits | Number |
| AccountKey | Unique account identifier. It comes empty when the account has no key | Text |
| CloseAccountInformationStatus | Status of the request at that moment | Number |
| Message | Message that informs the end customer of the status of the request, in Portuguese | Text |
| URLCloseAccount | Link to the closing document. Only sent when the status is 5 (Approved) | Text |
| Bank, BankBranch, BankAccount and BankAccountDigit | Internal bank data of the account | Text |
| Method | Webhook name. Fixed value: UpdateCloseAccount | Text |
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:
| Value | Status | Message | Meaning and what the BU must do |
|---|---|---|---|
| 0 | Created | Solicitação em análise | The request was registered. The BU must wait for the next statuses. |
| 1 | Processing | Name of the status | The closing is in progress. The BU must wait. |
| 2 | Error | Name of the status | There 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. |
| 3 | Pending | Description of the pending item | The request is pending. The BU must wait for the next statuses. |
| 4 | Disapproved | Solicitação de cancelamento reprovada | Closing request disapproved. |
| 5 | Approved | Conta cancelada com sucesso | The account was closed. It is the only status in which the BU must consider the account closed. |
| 6 | AutomaticClosingRequest | Prezado(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) | Meaning | What the BU must do |
|---|---|---|
| Gerada | The inclusion request was received and will be analyzed. | Wait for the analysis. This notice is not sent in every case. |
| Aprovado | The inclusion of the signer was approved. | Update the signer link in the BU system. |
| Reprovado | The 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:
| Field | Description | Type |
|---|---|---|
| Method | Webhook name. Fixed value: FBWebhookWorkerUpdateSignerSolicitation | Text |
| BusinessUnitId | Identifier of the BU, provided by Fits | Number |
| SignerSolicitationStatus | Status of the request. The values of SignerSolicitationStatus are listed in the Code Mapping, in the section Signer request status. | Text |
| Description | Message that corresponds to the status of the request, in Portuguese | Text |
| USN | Identifier of the inclusion request | Text |
| HolderPerson | Account holder (name of the company) | Text |
| SignerPerson | Signer (name of the person) | Text |
| RequestDate | Date of the request, in the format used by the server; there is no guarantee of ISO 8601 | Text |
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.
| Field | Description | Type |
|---|---|---|
| Method | Webhook name. Fixed value: AccountOperationLimitChangeWebhook | Text |
| BusinessUnitId | Identifier of the BU, provided by Fits | Number |
| Status | Decision on the request: Approved, PartiallyApproved or Denied | Text |
| NewMaxValue | Maximum value approved for the limit. It does not come when the request is denied. | Number |
| Message | Message 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:
| Field | Description | Type |
|---|---|---|
| Method | Webhook name. Fixed value: UpdatePersonContract | Text |
| BusinessUnitId | Identifier of the BU, provided by Fits | Number |
| ContractIdentifier | Unique identifier of the contract (a GUID). Use it to relate the notices of the same contract. | Text |
| HolderTaxNumber | CNPJ of the account holder (the company) | Text |
| TaxNumber | CPF of the buyer, who signs the contract | Text |
| ContractType | Type of the contract. The values are in the Code Mapping, section Contract type. | Number |
| ContractStatus | Status 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 |
| Account | Internal bank data of the account, which are not SPB data | Object |
| Account.Bank | Bank | Text |
| Account.BankBranch | Branch | Text |
| Account.BankAccount | Account | Text |
| Account.BankAccountDigit | Account check digit | Text |
The webhook is sent only with the statuses below:
| ContractStatus | Meaning | What 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.
| Topic | How it works |
|---|---|
| Authentication | Authentication 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 attempts | In 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 out | The event must be resent manually. |
| Expected response | HTTP 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. |
| Idempotency | There 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
- Handle each webhook idempotently, because the same event may arrive more than once.
- 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.
- Update your system only with the final result of each request.
- Reconcile periodically the requests that stayed without a final result, by querying the account or the corresponding tracking method.
- Release the end customer journey only after the approval.
Updated 11 days ago

