Como utilizar Webhooks no Stark Bank?

Entenda como utilizar webhooks para receber notificações das operações do Stark Bank.

Após a configuração das inscrições de Webhook no Stark Bank, sua aplicação estará pronta para receber notificações automáticas sobre eventos e logs gerados no sistema. Para garantir a resiliência e a segurança da sua integração, é fundamental seguir as boas práticas de gestão de eventos detalhadas abaixo:

Acompanhamento de Webhooks

Os eventos de Webhooks devem ser acompanhados via API, não há telas de acompanhamento pelo Internet Banking. Para mais informações de como ver esses eventos, leia a documentação de nossas APIs: https://starkbank.com/docs/api#webhook e https://starkbank.com/docs/api#event.

Comportamento de novas tentativas

Sempre que um evento for enviado ao seu servidor, o Stark Bank espera um código de status HTTP 200 como confirmação de recebimento.

• Falha na entrega: Caso o status 200 não seja retornado, o serviço realizará 3 tentativas automáticas nos seguintes intervalos: 5 minutos, 30 minutos e 120 minutos após a primeira tentativa.

Recomendamos a criação de uma rotina diária para consultar eventos que permaneçam com o status "não entregue" em seu controle, permitindo a regularização manual se necessário.

Ordenamento de eventos

O Stark Bank prioriza a performance na entrega das notificações. Por esse motivo, não há garantia de que os eventos cheguem na ordem cronológica em que foram gerados.

• Exemplo: Em uma operação de cobrança (invoice), os eventos paid (pago) ou credited (creditado) podem chegar antes do evento created (criado).

• Solução: Caso a ordem seja crítica para sua lógica de negócio, utilize o identificador da operação para consultar os logs completos via API e verificar os respectivos horários de criação.

Gestão de eventos duplicados

Em cenários específicos de rede ou reprocessamento, seu endpoint pode receber o mesmo evento mais de uma vez.

• Idempotência: Proteja sua integração registrando os IDs dos eventos já processados em seu banco de dados. Caso receba um ID já conhecido, ignore o processamento para evitar duplicidade de ações (como créditos ou baixas duplicadas).

Velocidade de resposta

Para garantir a estabilidade da comunicação, seu endpoint deve ser extremamente ágil.

1. Receba a requisição HTTP do Stark Bank.

2. Salve o evento em sua base de dados.

3. Retorne imediatamente o status 200.

• Processamento: Qualquer lógica de negócio complexa ou processamento de dados deve ocorrer de forma assíncrona, após o envio da resposta de sucesso ao Stark Bank.

---

A utilização correta de Webhooks permite que sua operação ganhe escala e automação com a segurança tecnológica que o mercado financeiro exige. Caso tenha dúvidas, contate nosso time de suporte.