Webhooks

A área Webhooks reúne os endereços cadastrados pela empresa para receber notificações e os eventos selecionados para cada destino. Acesse

Integração, Webhooks. Cada cadastro pertence ao ambiente selecionado.

Os eventos de Sandbox e Produção são enviados aos destinos cadastrados no respectivo ambiente. Sandbox usa dados de teste, mas realiza uma requisição HTTPS real ao seu endpoint. Use um destino de testes separado para evitar que uma simulação altere o seu sistema de produção.

Consulte Receber e validar eventos para implementar o receptor, validar a assinatura e tratar reentregas.

Para administrar os mesmos cadastros pelo seu sistema, use a API de Webhooks. A integração também pode consultar entregas e tentativas.

Consultar exige Webhooks. Criar, renomear, editar URL e eventos, pausar a fila, desativar, reativar, rotacionar e excluir são ações com permissões próprias e podem ficar bloqueadas quando a conta está em modo de consulta.

Se o seu endpoint restringe as origens das requisições, adicione os IPs oficiais da Raims à lista de permissões antes de receber os webhooks.

Cadastrar um webhook

Eventos disponíveis no Dashboard

O formulário organiza os eventos em cobranças e reembolsos. Os nomes abaixo identificam as categorias selecionadas no cadastro. Selecionar um tipo não cria uma ocorrência. O envio depende da confirmação do evento correspondente.

Última atividade do webhook

Última atividade mostra o horário da última tentativa de envio registrada, incluindo tentativas que falharam. Esse horário não confirma que o endpoint recebeu ou processou o evento e pode aparecer com atraso.

Sem registro significa que não há uma tentativa confirmada disponível para exibir. Isso não comprova que nunca houve envios. Indisponível significa que a informação não pôde ser consultada naquele momento; tente novamente depois.

Uma atividade antiga pode continuar visível mesmo quando os logs daquela tentativa já não estiverem no período disponível para consulta. O acesso a essa informação exige somente Webhooks; a consulta dos logs tem permissão própria.

Para investigar um episódio de falhas pela API, use Consultar a situação do webhook. Essa consulta mostra os horários disponíveis e a duração das falhas registradas, sem testar a URL do receptor.

Proteger o segredo

O segredo completo é um dado de autenticação. Guarde-o no ambiente privado da sua aplicação e limite o acesso a quem administra a integração. O identificador do webhook não substitui esse segredo.

Para conferir a autenticidade de cada requisição, siga a validação de assinatura usando o corpo original recebido.

Não envie o segredo ao suporte nem o inclua em capturas de tela. Se houver suspeita de exposição, rotacione o segredo e atualize a configuração que o utiliza. Consulte o estado atual da cobrança ou do estorno pela API antes de tomar uma decisão financeira.

Renomear um webhook

1. Acesse Integração, Webhooks e abra as ações do destino.
2. Selecione Renomear webhook, informe o novo nome e confirme a alteração.
3. Confira o nome atualizado na lista.

A ação exige Editar webhooks. Renomear não altera a URL nem os eventos.

Editar URL e eventos

A ação Editar URL e eventos altera o endereço de recebimento e a seleção de eventos do mesmo cadastro. Exige Webhooks e Editar URL e eventos de webhooks, além da confirmação de identidade solicitada pelo Dashboard. A URL segue as mesmas regras do cadastro, e pelo menos um evento precisa permanecer selecionado.

Nome, identificador, segredo e status são preservados. Editar a configuração não reativa um webhook desativado, não reinicia a contagem de falhas e não prolonga os prazos de novas tentativas.

As alterações valem para as próximas seleções e tentativas de envio. Ao remover um tipo de evento, ele deixa de ser autorizado para novos envios. Requisições já autorizadas ou em andamento podem terminar com a configuração anterior. Ao incluir um tipo, também podem ser enviados eventos anteriores que ainda aguardavam preparação. A edição não reenvia entregas já encerradas.

Eventos antigos já selecionados podem ser mantidos ou removidos, mesmo quando não estão mais disponíveis para novos cadastros. Se você remover um desses eventos e salvar, ele não poderá ser selecionado novamente enquanto estiver fora do catálogo atual.

Pausar e retomar a fila

Use Pausar fila no menu do webhook antes de uma manutenção no receptor. Confira o aviso e conclua a confirmação de identidade. A ação exige Webhooks e Editar URL e eventos de webhooks e está disponível para um cadastro ativo.

A indicação Fila pausada confirma a configuração. As entregas pendentes e os novos eventos selecionados aguardam, mas seus prazos continuam contando: até 72 horas em Produção e quatro horas no Sandbox. Requisições já autorizadas podem terminar. Se o prazo de uma entrega acabar durante a pausa, ela não será enviada na retomada.

Depois da manutenção, escolha Retomar fila no mesmo menu e confirme. As entregas ainda válidas voltam a poder ser enviadas, conforme os limites de envio. A retomada não garante entrega imediata nem uma ordem específica. Pausar e retomar encerram o episódio anterior de falhas, sem comprovar que o receptor se recuperou. Confira o resultado nos logs.

Para controlar a pausa pela integração, use Pausar ou retomar a fila. Um teste técnico pode ser solicitado durante a pausa para conferir o receptor antes de retomar.

Desativar e reativar um webhook

As ações Desativar webhook e Reativar webhook exigem Editar webhooks e a confirmação de identidade solicitada pelo Dashboard. Elas preservam o cadastro, o segredo e os eventos selecionados.

Um webhook desativado não recebe novos envios. Se uma tentativa pendente encontrar o cadastro desativado, a entrega é encerrada. Reativar antes dessa tentativa permite que a entrega continue dentro do prazo original. A ação não reenvia o histórico nem recupera entregas encerradas automaticamente. O reenvio manual permite solicitar outra entrega de um evento elegível.

Para manutenção com preservação das entregas ainda válidas, use Pausar e retomar a fila. Se um cadastro for desativado enquanto a fila estiver pausada, reativá-lo mantém a pausa; use Retomar fila para liberar os envios.

As falhas não pausam nem desativam o cadastro automaticamente. Corrija o receptor e acompanhe as novas tentativas, que continuam dentro dos limites de cada entrega. Consulte Falhas e novas tentativas de webhook e os alertas de falhas.

Rotacionar a assinatura

1. Acesse Integração, Webhooks e abra as ações do destino correto.
2. Selecione Rotacionar assinatura.
3. Confira o aviso, confirme a rotação e guarde o novo segredo.
4. Atualize o receptor e confira se ele aceita eventos com o novo segredo.

A ação exige Rotacionar webhooks e mantém o identificador do cadastro. No Dashboard, a troca é imediata: os novos envios usam somente o segredo novo assim que a rotação é confirmada. Se houver uma transição iniciada pela API, a rotação no Dashboard também encerra essa transição e substitui os dois segredos anteriores.

Atualize o receptor para evitar rejeições. Requisições já autorizadas ou em andamento ainda podem chegar com uma assinatura anterior. Em caso de vazamento, retire também os segredos antigos da configuração do receptor. A rotação não reativa um webhook desativado nem zera a contagem de falhas.

A API permite escolher um período de transição para uma troca planejada. Essa opção não é usada pelo Dashboard.

Excluir um webhook

1. Acesse Integração, Webhooks e abra as ações do destino que deseja remover.
2. Selecione Excluir webhook, confira o destino e confirme a exclusão.
3. Aguarde o resultado e confira a lista.

A ação exige Excluir webhooks e remove o destino permanentemente. Confira antes se algum sistema depende dele. A exclusão impede novos envios para esse cadastro. Requisições já autorizadas ou em andamento ainda podem terminar.