Webhooks

Webhooks avisam sua aplicação quando um evento acontece na Raims, como o pagamento de uma cobrança ou a conclusão de um estorno. Cadastre o endereço que receberá essas notificações e selecione os eventos usados pelo seu sistema.

A API permite administrar os mesmos cadastros apresentados no Dashboard. Para consultar o resultado dos envios, use Entregas de webhooks.

Concluir a primeira integração

1. Prepare o receptor para validar a assinatura e aceitar o evento antes de processá-lo.
2. Consulte os tipos de evento e selecione os que sua aplicação vai tratar.
3. Cadastre o destino no Sandbox com is_active: false. Guarde o id retornado e configure o secret_key no servidor do receptor.
4. Ative o cadastro, solicite um teste e consulte a entrega retornada. Confira também o recebimento nos registros da sua aplicação.
5. Use Simulação para gerar os eventos financeiros que seu sistema precisa tratar. Verifique as atualizações esperadas e o tratamento de duplicatas.

O evento técnico confere o caminho até o receptor e a assinatura. Os testes financeiros conferem a reação da sua aplicação a eventos como charge.paid. Ao preparar Produção, use a chave, o cadastro e o segredo desse ambiente.

Cadastrar o destino

Antes de criar um webhook, prepare uma URL HTTPS que aceite POST com JSON. Use um domínio controlado pela sua empresa, com DNS que resolva para um IPv4 público, na porta padrão 443. O endereço não pode ser localhost, um IP direto nem conter usuário ou senha.

Informe um nome que identifique o sistema e sua finalidade, a URL e os eventos que deseja receber. Guarde o id para administrar o cadastro e o secret_key para validar a assinatura. Consultas posteriores não retornam o segredo.

O cadastro começa ativo. Se o receptor ainda não estiver pronto, use is_active: false e ative-o depois pela atualização. A mesma URL não pode ser cadastrada duas vezes na empresa e no ambiente da chave.

O receptor deve validar cada assinatura, reconhecer entregas repetidas e responder dentro do prazo de envio. Siga Receber e validar eventos para implementar esse tratamento. Se houver restrição de origem, permita os IPs oficiais da Raims.

Selecionar os eventos

Liste os tipos de evento para obter os códigos disponíveis no cadastro. Informe esses códigos em events e mantenha ao menos um selecionado. Assinar um evento não cria uma ocorrência; a notificação depende da mudança correspondente.

Selecione somente os eventos que seu sistema precisa processar. O evento técnico webhook.test é enviado pelo comando de teste e não faz parte da seleção de eventos do cadastro.

Consultar e alterar a configuração

Liste os webhooks ou consulte um cadastro pelo id. As consultas retornam a configuração e a situação do destino, sem o segredo de assinatura.

Para atualizar o cadastro, envie somente os campos que deseja alterar, com ao menos um campo na requisição. Omitir um campo preserva seu valor atual. Alterar o nome, a URL ou os eventos mantém o identificador e o segredo. Campos enviados precisam manter um valor válido: null, nome ou URL vazios e lista de eventos vazia não limpam a configuração.

A edição de URL e eventos vale para as próximas seleções e tentativas de envio. Requisições já autorizadas ou em andamento podem terminar com a configuração anterior. Adicionar um tipo pode incluir eventos anteriores que ainda aguardavam preparação; a alteração não reenvia entregas já encerradas. Eventos antigos que continuam selecionados podem ser mantidos ou removidos, mas só podem ser adicionados novamente se estiverem no catálogo atual.

Consultar a situação do destino

Consulte a situação do webhook para saber se há um episódio de falhas registrado. A resposta reúne os horários disponíveis da primeira e da última falha do episódio, do último sucesso e da atualização dessas informações.

Enquanto o status for failing, failure_duration_seconds informa há quanto tempo começou o episódio. Os horários de falha pertencem ao momento em que seu resultado foi registrado; não são a data de criação do evento. Uma entrega aceita com HTTP 2xx encerra o episódio. A desativação também o encerra, por isso um destino desativado pode não ter horários de falha.

As informações vêm das tentativas de envio e podem aparecer com atraso. observed_at informa a última atualização disponível. A consulta não testa a URL nem monitora sua disponibilidade continuamente. Use o teste de recebimento quando precisar conferir uma nova chamada; o resultado desse teste não altera a situação registrada.

Pausar e retomar a fila

Pause a fila antes de uma manutenção no seu receptor. Envie is_paused: true para um webhook ativo. A Raims mantém as entregas pendentes e inclui os novos eventos selecionados, mas não inicia seus envios enquanto a pausa estiver ativa. Uma requisição já autorizada pode terminar.

A pausa não congela nem amplia os prazos: entregas financeiras continuam limitadas a 72 horas em Produção e quatro horas no Sandbox. Uma entrega cujo prazo acabar durante a pausa não será enviada na retomada.

Depois de corrigir ou atualizar o receptor, envie is_paused: false no mesmo endpoint. A retomada libera as entregas ainda válidas, de acordo com os limites de envio existentes. Ela não garante envio imediato, uma ordem específica ou a recuperação de entregas encerradas.

As consultas de configuração informam is_paused e paused_at. Pausar ou retomar encerra o episódio anterior de falhas. Isso não confirma que o receptor se recuperou; confira as tentativas depois da retomada. A pausa é separada de is_active: o cadastro continua ativo e mantém sua configuração.

O teste técnico pode ser solicitado durante a pausa para conferir o receptor antes de retomar a fila. Ele mantém uma tentativa HTTP e prazo de cinco minutos, sem alterar a situação de falhas do cadastro.

Desativar e reativar

Use is_active: false na atualização para desativar o destino e is_active: true para reativá-lo. O cadastro, o segredo e a seleção de eventos são preservados.

Desativar impede novos envios. Uma entrega pendente é encerrada se sua próxima tentativa encontrar o destino desativado. Se a reativação ocorrer antes, a entrega pode continuar dentro do prazo original. Reativar não reenvia o histórico nem recupera entregas encerradas.

Falhas não pausam nem desativam o destino automaticamente. A Raims continua tentando cada entrega dentro dos limites de seu ambiente. Alterar nome, URL, eventos ou segredo não reativa um cadastro desativado manualmente.

Para uma manutenção com preservação das entregas ainda válidas, use Pausar e retomar a fila.

Se a fila estiver pausada, reativar o cadastro mantém essa pausa. Retome a fila separadamente quando o receptor estiver pronto.

disabled_reason: manual identifica a desativação manual. Cadastros desativados anteriormente por falhas podem manter continuous_failure; confira e reative esses cadastros quando o receptor estiver pronto. Quando o webhook está ativo, esse campo fica null.

Rotacionar o segredo

Solicite a rotação quando precisar substituir o segredo de assinatura. O identificador do webhook permanece o mesmo. Guarde o novo secret_key e atualize o receptor. Consultas de configuração não recuperam esse valor. Prepare o armazenamento seguro antes de solicitar a rotação.

O período de transição permite receber assinaturas do segredo novo e do anterior enquanto sua aplicação é atualizada. Por padrão, ele dura 24 horas. Use grace_period_seconds: 0 se houver suspeita de vazamento ou se precisar substituir o segredo imediatamente. Nesse caso, novos envios usam somente o novo segredo assim que a rotação é confirmada. Se houver uma transição ativa, ela é encerrada e os dois segredos anteriores são substituídos. Requisições já autorizadas ou em andamento ainda podem chegar com uma assinatura anterior. Retire os segredos antigos da configuração do receptor para que deixem de ser aceitos.

Durante a transição, repetir a rotação com um período maior que zero retorna o mesmo segredo novo e o mesmo prazo, sem prorrogá-lo. Confira previous_secret_expires_at e aceite qualquer assinatura v1 válida, conforme a validação de assinatura.

No Dashboard, a rotação sempre usa a troca imediata. A escolha do período de transição fica disponível na API.

Testar o recebimento

Envie um evento de teste para um webhook ativo. A requisição não recebe corpo e retorna event_id e delivery_id para acompanhamento. O aceite do pedido não confirma que o receptor o recebeu.

O evento tem type: webhook.test, data.object: webhook e data.id com o identificador do cadastro. Ele usa a URL e a assinatura do webhook e faz uma requisição HTTPS real. Não cria nem altera cobranças, pagamentos, estornos ou saldos.

O teste realiza uma tentativa HTTP, com prazo de até cinco minutos para o envio. Se ela falhar, corrija o receptor antes de solicitar outro teste. O resultado desse teste não altera a contagem de falhas nem provoca a desativação automática do cadastro.

Cada nova requisição de teste cria outro evento. Para testar novamente, use esse mesmo endpoint; eventos webhook.test não aceitam reenvio pelo recurso de entregas.

Para verificar o tratamento de eventos financeiros, use Simulação com uma chave Sandbox. Mantenha os efeitos desses testes separados dos dados de produção da sua aplicação.

Excluir um destino

Exclua o webhook quando ele deixar de ser usado. A exclusão impede novos envios para aquele cadastro. Requisições já autorizadas ou em andamento ainda podem terminar.

Confira antes se algum sistema depende do destino. Para interromper o recebimento e manter a configuração, desative o cadastro. As entregas e tentativas continuam disponíveis por 30 dias a partir da criação de cada entrega, mas não podem ser reenviadas para um cadastro excluído.

Empresa e ambiente

Todas as requisições exigem uma chave de API. A empresa e o ambiente vêm dessa chave: uma chave Sandbox administra somente os webhooks do Sandbox, e uma chave de Produção administra somente os de Produção. O console desta documentação aceita apenas chaves Sandbox.

As chamadas de integração usam a autenticação por chave. As permissões e as confirmações de identidade solicitadas pelo Dashboard pertencem às ações feitas naquela interface.

Sandbox envia requisições HTTPS reais. Use um destino de testes separado e proteja o segredo no servidor da sua aplicação. Nunca o envie ao suporte ou o inclua em capturas de tela, URLs e logs.