Um webhook é um retorno de chamada web que a Belvo usa para enviar notificações sobre um link específico. Você precisará configurar webhooks para usar as APIs da Belvo.
Para configurar sua URL de webhook:
- Faça login no seu Portal de Débito Direto. (Login Sandbox | Login Produção)
- Vá para Desenvolvedores -> Webhooks. (Webhooks Sandbox | Webhooks Produção)
- Insira sua URL.
- Clique em Set.
✅ Sua URL de webhook foi adicionada com sucesso.
{
"eventType": "payment_request_update",
"eventCode": "payment_request_successful",
"datetime": "2022-01-01T12:34:56.789Z",
"details": {
"id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5",
"reference": "your_reference_here",
"status": "successful",
"failedReason": null,
"failedMessage": null
}
}| Parâmetro | Tipo | Descrição |
|---|---|---|
eventType | string | O tipo do evento do recurso da API. Pode ser um dos seguintes: customer_update, payment_method_update ou payment_request_update. |
eventCode | string | O código do evento do webhook. Para detalhes sobre os valores possíveis, consulte a seção Códigos de Evento do Webhook abaixo. |
datetime | string | O timestamp ISO-8601 quando o evento foi enviado. |
details | object | Um objeto contendo dados específicos sobre o evento. |
details.id | string | O ID Belvo do recurso da API (Cliente, Método de Pagamento ou Solicitação de Pagamento) ao qual o evento está relacionado. |
details.reference | string | Se você forneceu uma reference ao criar o recurso, uma descrição opcional do objeto. |
details.status | string | O status do recurso. |
| string | Se o status for Para detalhes sobre o |
| string | Se o status for Para detalhes sobre o |
details.documentNumber | string | Se o evento estiver relacionado a um cliente, este campo contém o RFC ou CURP do cliente relacionado ao método de pagamento por débito direto. Este campo está disponível apenas para eventos relacionados a clientes. |
Para informações sobre payloads específicos para um determinado recurso da API e código de webhook, basta clicar no Código do Evento do webhook na tabela abaixo.
| Recurso | Tipo de Evento | Código de Evento | Enviado sempre que... |
|---|---|---|---|
| Clientes | customer_update | customer_blocked | o cliente relacionado ao método de pagamento por débito direto foi bloqueado devido a atividade suspeita. |
| Clientes | customer_update | customer_unblocked | o cliente relacionado ao método de pagamento por débito direto foi desbloqueado após revisão pelas partes relevantes. |
| Métodos de Pagamento | payment_method_update | payment_method_registration_successful | o registro do método de pagamento por débito direto foi bem-sucedido. |
| Métodos de Pagamento | payment_method_update | payment_method_registration_failed | o registro do método de pagamento por débito direto falhou. |
| Métodos de Pagamento | payment_method_update | payment_method_registration_canceled | o registro do débito direto foi cancelado (geralmente pelo proprietário). |
| Solicitações de Pagamento | payment_request_update | payment_request_successful | o pagamento foi bem-sucedido e recebemos confirmação do provedor de infraestrutura de pagamento. |
| Solicitações de Pagamento | payment_request_update | payment_request_failed | um erro é relatado pelo provedor de infraestrutura de pagamento. |
| Solicitações de Pagamento | payment_request_update | payment_request_chargeback | um chargeback foi feito pelo seu cliente. |
Quando você receber um webhook da Belvo, certifique-se de responder com um código de status 2XX (por exemplo, um 200). Se o sistema da Belvo não receber uma resposta 200 do seu servidor, tentaremos automaticamente reenviar a solicitação. Para mais detalhes, consulte nossa seção de Política de Retentativas.
Quando a Belvo não recebe uma resposta 2XX do seu servidor, tentamos enviar o webhook novamente a cada 60 minutos por até 10 tentativas.
Por exemplo, se a primeira tentativa (inicial) falhar, nosso sistema espera 60 minutos antes de tentar novamente e continuará nesse padrão até que receba uma resposta bem-sucedida ou atinja o máximo de 10 reintentos.