Entregas de webhooks

Consulte o que aconteceu entre a criação de um evento e a resposta do seu receptor. Use a lista de entregas para acompanhar o andamento e os detalhes de cada tentativa para investigar falhas.

Para cadastrar um destino ou alterar os eventos recebidos, use Webhooks.

Evento, entrega e tentativa

Um evento descreve uma mudança, como charge.paid. A entrega é o envio desse evento a um webhook. Uma tentativa é cada chamada HTTP feita para concluir a entrega.

Uma entrega pode ter várias tentativas, todas com o mesmo webhook-id. Use o identificador devolvido pela consulta de tentativas ao recuperar seu detalhe; ele é diferente dos IDs do evento e da entrega.

Use o evento para evitar repetir seu efeito no sistema e a entrega para reconhecer novas tentativas. Veja Tratar reentregas e ordem.

Acompanhar uma entrega

Liste as entregas e use o id de um resultado para consultá-lo. As informações de andamento podem aparecer com atraso; a ausência de um registro não comprova que o evento nunca foi enviado.

A lista apresenta as entregas mais recentes primeiro. Você pode filtrar pelo webhook, tipo de evento, situação e período de criação da entrega. Se já tiver o UUID do evento, use event_id para reunir suas entregas, inclusive reenvios manuais. Para localizar primeiro o evento pelo recurso, consulte Eventos de webhooks. Os limites created_gte e created_lte são inclusivos. A consulta abrange até 30 dias desde a criação da entrega, mesmo se você omitir o período.

Comece a listagem sem cursor, processe list e copie page.next_after para after enquanto page.has_next for verdadeiro. Preserve filtros durante a navegação. Para voltar, use page.previous_before em before. Copie o cursor inteiro e não envie os dois sentidos na mesma requisição. Veja Listagem e paginação.

Datas do acompanhamento são retornadas em segundos Unix UTC. event_created_at identifica a criação do evento original; created_at identifica a entrega. No reenvio, essas datas podem ser diferentes. deadline_at é o limite para tentar concluir a entrega, e next_attempt_at informa a próxima tentativa prevista quando disponível. Consultas não iniciam nem aceleram envios.

Uma fila pausada impede novas tentativas, mas conserva o prazo original da entrega. Confira is_paused na configuração do webhook antes de investigar uma espera. Veja Pausar e retomar a fila.

Uma resposta HTTP 2xx confirma que o receptor aceitou a entrega. Ela não comprova o processamento posterior no sistema de destino. Confira também os registros da sua aplicação.

Consultar tentativas e respostas

Para consultar pela API a resposta HTTP e o corpo de uma tentativa de webhook, liste as tentativas da entrega e consulte uma delas para ver os detalhes disponíveis. O registro informa a resposta HTTP, a duração, o erro e o destino usado quando esses dados foram capturados.

A lista reúne chamadas HTTP ao receptor. Uma espera anterior ao envio não é uma tentativa HTTP e pode manter a entrega pendente com a lista ainda vazia. As tentativas aparecem da mais recente para a mais antiga. Use a paginação para percorrer o histórico completo disponível.

Nas tentativas, created_at informa a conclusão da tentativa. duration_ms mede o tempo total da tentativa, que pode incluir preparação e espera antes da chamada HTTP. Não use esse valor isoladamente como tempo de resposta do seu receptor.

status_code: null indica que não há status HTTP disponível. Nesse caso, o erro pode ajudar a identificar uma falha de conexão ou timeout. Uma tentativa que falhou não significa que a entrega terminou: consulte seu andamento e a próxima tentativa prevista.

destination_ip identifica o destino usado naquela conexão. Se houver um proxy na frente do receptor, esse IP pode ser o do proxy. O campo não informa o IP de origem da Raims nem o resultado atual de uma consulta DNS.

Os corpos de requisição e resposta ficam no detalhe da tentativa. request_available e response_body_available informam sua disponibilidade. Um corpo indisponível difere de um corpo vazio que foi registrado. response_body_truncated: true indica uma captura parcial; o conteúdo pode não ser um JSON completo. A captura da resposta tem limite de 8 KiB. Respostas binárias, comprimidas ou sem texto UTF-8 válido também podem ficar indisponíveis.

Registros antigos podem não conter corpo, URL ou IP. A existência dos metadados não garante que esses dados tenham sido capturados. Não coloque segredos nem dados pessoais desnecessários nas respostas do receptor.

Histórico por 30 dias

A API mantém a entrega, suas tentativas e os corpos capturados disponíveis para consulta por 30 dias a partir da criação da entrega, indicada em created_at. Depois desse prazo, eles deixam de aparecer nas consultas. Uma nova tentativa da mesma entrega não reinicia os 30 dias.

Um reenvio cria outra entrega, com seu próprio prazo de consulta. O limite para solicitar esse reenvio continua sendo 15 dias a partir da criação do evento original, indicada em event_created_at. Guardar o histórico por 30 dias não amplia esse prazo.

No Dashboard, os logs de cada tentativa podem ser consultados por 30 dias a partir da conclusão daquela tentativa. Por isso, um registro ainda pode aparecer nos logs depois de terminar o prazo da entrega na API.

Investigar uma falha

Consulte a entrega e abra a tentativa mais recente. O status HTTP da tentativa foi retornado pelo receptor ou por uma camada à frente dele; ele é diferente do status da requisição usada para consultar a API Raims.

Se uma consulta ampla de entregas retornar 503, aguarde e tente um período menor ou filtros mais específicos. Confira também a orientação geral de indisponibilidade da API.

Confira URL, certificado, assinatura e regras de firewall antes de solicitar outro envio. Os prazos automáticos de Produção e Sandbox estão em Falhas e novas tentativas de webhook.

Antecipar uma tentativa

Se o receptor já foi corrigido e a entrega ainda aguarda uma tentativa, use Antecipar uma tentativa. A entrega precisa estar pendente, dentro do prazo, com webhook ativo e fila sem pausa.

A ação pede que a próxima tentativa fique apta a ocorrer antes do horário previsto, conforme os limites de envio. Ela preserva o evento e a entrega; o delivery_id permanece o mesmo. Não cria outra entrega, não amplia o prazo e não aumenta a quantidade de tentativas permitidas no Sandbox.

Uma resposta 202 confirma o recebimento do pedido. A condição da entrega é conferida novamente antes de antecipar o envio, pois ela pode mudar nesse intervalo. Consulte a mesma entrega para acompanhar o resultado. Uma tentativa em andamento ou uma entrega já encerrada não pode ser antecipada. Para uma entrega encerrada, confira a elegibilidade de reenvio.

O evento técnico webhook.test não aceita antecipação. Se precisar testar novamente o receptor, use Enviar um evento de teste.

Reenviar um evento

Solicite o reenvio a partir de uma entrega do evento. Ele precisa ter sido criado há no máximo 15 dias, manter o corpo disponível e continuar selecionado em um webhook ativo.

Se você tem o ID do evento e precisa escolher o destino, use Enviar um evento para um webhook. Esse caminho permite a primeira entrega para o cadastro e segue os mesmos limites de elegibilidade.

O pedido retorna event_id e delivery_id. Consulte a nova entrega para acompanhar o resultado. O aceite do pedido não confirma o recebimento e não cancela as tentativas automáticas da entrega anterior. O registro pode levar alguns instantes para aparecer na consulta após o aceite; aguarde brevemente antes de consultar de novo.

Se a fila estiver pausada, a nova entrega também aguarda a retomada, enquanto seu próprio prazo de tentativas continua contando.

O reenvio preserva os bytes do corpo original, inclusive seu id e created_at, e usa a URL e o segredo atuais do webhook. Prepare o receptor para receber o mesmo evento em entregas diferentes sem repetir seu efeito. Reenviar não repete a transação financeira que originou o evento.

A nova entrega tem seu próprio prazo de tentativas. O limite para solicitar outro reenvio continua vinculado à criação do evento original; reenviar não renova os 15 dias. Veja Reenvio manual de eventos.

Eventos webhook.test não aceitam reenvio. Para conferir novamente o receptor, solicite outro teste.

Excluir um webhook preserva o histórico disponível para consulta. Use seu identificador como filtro para localizar as entregas anteriores. A exclusão impede o reenvio para aquele cadastro.

Reenviar vários eventos

Use Reenviar vários eventos para solicitar entregas de até 500 IDs em uma requisição. Cada item segue as mesmas condições do reenvio individual. Você pode reunir entregas de webhooks diferentes da mesma empresa e ambiente.

A resposta mantém a ordem dos IDs enviados. Para cada item aceito, ela retorna o evento original e a nova entrega. Um item recusado traz o motivo em error, sem impedir o aceite dos demais. HTTP 202 confirma o processamento do pedido; confira cada resultado antes de acompanhar as novas entregas.

Se o mesmo ID aparecer mais de uma vez, ou se várias entregas se referirem ao mesmo evento e webhook, o pedido cria uma única nova entrega para esse par. Os resultados correspondentes retornam o mesmo delivery_id.

Reenviar não cancela as tentativas anteriores, inclusive as que estejam em andamento. Corrija o receptor antes de enviar o pedido e mantenha a deduplicação pelo ID do evento. Se uma falha impedir a resposta da API, parte dos itens pode ter sido aceita. Consulte as entregas antes de repetir todo o pedido.

Empresa e ambiente

Use uma chave de API da mesma empresa e do mesmo ambiente dos webhooks. Filtros e identificadores não dão acesso a dados de outra empresa ou ambiente. O console aceita somente chaves Sandbox.

As consultas não modificam a entrega ou o recurso financeiro. Preserve as chaves e os segredos no ambiente privado da integração.