Eventos de webhooks

Um evento registra uma mudança na Raims, como o pagamento de uma cobrança. Ele tem um identificador próprio, diferente dos IDs das entregas e das tentativas de envio. Use esta consulta quando tiver o ID recebido no corpo do webhook ou precisar encontrar os eventos de uma cobrança.

Localizar um evento

Liste os eventos da empresa e do ambiente da chave. Você pode filtrar por tipo, recurso e período de criação. Use resource_id com o identificador público do recurso, como o ch_ de uma cobrança ou o rf_ de um estorno. Esse campo não recebe o ID do evento nem da entrega.

created_gte e created_lte são segundos Unix UTC, com limites inclusivos. A lista apresenta os eventos mais recentes primeiro. Comece sem cursor, processe list e copie page.next_after para after enquanto page.has_next for verdadeiro. Mantenha os mesmos filtros. Para voltar, use page.previous_before em before, sem combinar os dois cursores. Veja Listagem e paginação.

Cada item informa o ID, o tipo, a criação do evento e o recurso relacionado. Um reenvio manual mantém o mesmo evento e não cria outra ocorrência na listagem. O teste webhook.test cria um evento próprio para o webhook testado.

Consultar o conteúdo original

Use Recuperar um evento com o UUID do evento. Além dos dados da listagem, a resposta inclui payload, uma string com o JSON original. Interprete essa string como JSON quando precisar ler seus campos. A consulta não envia o evento ao seu receptor.

O created_at da consulta usa segundos Unix UTC. Dentro de payload, o created_at original continua em ISO 8601. O conteúdo registra o evento naquele momento; consulte o recurso correspondente para conhecer seu estado atual.

O conteúdo pode incluir dados da integração. Limite o acesso às pessoas e sistemas autorizados e não o envie ao suporte com informações sensíveis. Para validar notificações recebidas por HTTP, use a assinatura dos webhooks.

Encontrar as entregas do evento

Use o filtro event_id em Listar entregas para encontrar os envios do mesmo evento, incluindo os reenvios manuais ainda disponíveis no histórico. Cada destino e cada reenvio têm seu próprio delivery_id.

A existência de um evento não confirma que houve entrega. Ele pode não ter um destino selecionado ou seu envio ainda pode estar aguardando. Uma resposta HTTP 2xx em uma tentativa confirma somente o aceite pelo receptor, não o processamento posterior no sistema de destino.

Enviar para um webhook

Use Enviar um evento para um webhook com o event_id no caminho e o webhook_id no corpo. Você pode escolher um destino da mesma empresa e ambiente, inclusive quando ele não tinha uma entrega anterior desse evento.

O evento precisa ter sido criado há no máximo 15 dias, com o corpo original disponível. O webhook deve estar ativo e selecionar o tipo do evento no momento do pedido. A consulta por 30 dias não amplia essa elegibilidade. Eventos webhook.test exigem outro teste.

A resposta 202 retorna o evento original e o identificador da nova entrega. Consulte essa entrega para acompanhar o resultado. O envio usa a URL e os segredos atuais do cadastro e preserva o corpo original, incluindo id e created_at. O pedido não altera o recurso financeiro nem cancela outras entregas do mesmo evento.

Se a fila estiver pausada, a nova entrega aguarda a retomada, com prazo próprio de até 72 horas em Produção ou quatro horas no Sandbox. Seu receptor precisa reconhecer o mesmo evento em entregas diferentes para evitar repetir seus efeitos. Depois de uma resposta incerta da API, consulte as entregas por event_id antes de fazer outro pedido.

Histórico e ambiente

Os eventos ficam disponíveis por 30 dias desde sua criação original. Novas tentativas e reenvios não reiniciam esse prazo. O histórico de uma entrega tem seu próprio período, explicado em Histórico por 30 dias.

As consultas exigem uma chave de API da mesma empresa e ambiente. O console aceita somente Sandbox. Os registros podem levar alguns instantes para aparecer; uma lista vazia não comprova que uma mudança financeira deixou de acontecer. Consulte a cobrança ou o estorno quando precisar confirmar seu estado.