Webhooks
Cadastre destinos HTTPS, selecione eventos e opere segredos e entregas pelo Dashboard.
Webhooks notificam a aplicação da empresa quando eventos selecionados ocorrem na Raims. A configuração é feita em
Integração, Webhooks e pertence ao ambiente atualmente selecionado.
Cadastrar um webhook
Prepare o endereço de recebimento
Disponibilize uma URL HTTPS controlada pela sua empresa. O endereço não pode usar localhost, IP direto nem incluir usuário ou senha.
Dê um nome claro
Identifique sistema, finalidade e ambiente, por exemplo ERP - pagamentos Sandbox.
Selecione ao menos um evento
Escolha somente os grupos que o seu sistema realmente precisa acompanhar.
Guarde o segredo
O segredo será usado para confirmar que uma notificação foi enviada pela Raims. Guarde-o na parte privada da sua aplicação e nunca o exponha no navegador ou em logs.
Eventos disponíveis no Dashboard
O formulário apresenta dez eventos, organizados em cobranças, reembolsos e chargebacks. Selecione somente os códigos que a aplicação precisa processar.
Propriedade
Tipo
Detalhes técnicos em preparação
O formato dos eventos e a validação da assinatura serão documentados na Referência da API antes da liberação da integração pública.
Preparar sua aplicação
Notificações podem ser reenviadas ou chegar fora da ordem esperada. A aplicação deve tratar cada entrega de forma idempotente, reconhecer uma notificação já processada e consultar o estado mais recente antes de tomar uma decisão financeira.
Confirme a origem
Valide a assinatura usando exatamente as instruções que serão publicadas na Referência da API.
Implemente idempotência
Use o identificador único da notificação como chave de idempotência. Antes de executar uma ação, tente registrar essa chave de forma atômica em armazenamento durável com garantia de unicidade. Somente a entrega que criar o registro deve iniciar o processamento. Entregas simultâneas ou reenvios com a mesma chave devem consultar o registro existente e não repetir uma ação em andamento ou já concluída. Registre também o estado do processamento para permitir uma nova tentativa segura quando a execução anterior falhar.
Responda rapidamente
Confirme o recebimento depois de armazenar a notificação com segurança. Se o trabalho for demorado, continue o processamento dentro da sua aplicação.
Consulte o estado atual
Quando a decisão depender do status mais recente de uma cobrança ou disputa, confirme esse status pela integração em vez de depender apenas da ordem das notificações.
Eventos diferentes não são duplicados
Duas notificações com identificadores diferentes devem ser avaliadas separadamente, mesmo quando pertencem à mesma cobrança, ao mesmo reembolso ou ao mesmo chargeback. Faça a deduplicação pelo identificador da notificação, não pelo cliente, recurso, status ou horário recebido.
Validar o segredo
Aguarde a especificação oficial
Não implemente a validação por tentativa. O formato exato da assinatura será publicado antes que os webhooks possam ser integrados pela API Pública.
Operação no Dashboard
Consulte as entregas recentes do webhook e o resultado apresentado pelo Dashboard. Confirme separadamente se o seu sistema concluiu o processamento.
Altera o rótulo no Dashboard sem mudar a URL nem o comportamento das entregas.
Invalida o segredo anterior imediatamente. Atualize o receptor de forma coordenada para não rejeitar eventos futuros.
Remove o webhook permanentemente. Confirme que nenhum sistema depende do destino antes de executar a ação.