Quando entra dinheiro por PIX em uma conta que você gerencia, a PrismaPay envia um POST assinado para a URL que você cadastrou. É o único canal que avisa em tempo real; o restante você consulta.

Eventos disponíveis hoje

O crédito só gera evento depois de verificado na origem. Você nunca recebe um aviso de dinheiro que não entrou.
Cash-out não emite webhook. Quando as rotas de pagamento forem liberadas, o resultado do cash-out volta na própria resposta da chamada.

Formato do evento

Headers: Corpo:

Verifique a assinatura

A receita é a mesma do padrão Stripe: o valor assinado é ${t}.${corpo bruto}.
Verifique sobre o corpo bruto, os bytes exatos que chegaram. Se o seu framework fizer JSON.parse e você re-serializar, a assinatura não bate. No Express, use express.raw({ type: "application/json" }) nessa rota.

Como responder

1

Responda 2xx rápido

Grave o evento e devolva 200 imediatamente. Processe depois, de forma assíncrona. Uma resposta lenta vira timeout e entra na fila de retry.
2

Deduplique por X-PrismaPay-Delivery

O mesmo id chega em toda retentativa da mesma entrega. Use-o como chave única do seu lado.
3

Não confie na ordem de chegada

A ordem não é garantida. Decida pelo conteúdo do evento, nunca pela sequência em que ele chegou.

Retentativas

Uma resposta diferente de 2xx, ou um timeout, entra em duas fases:
1

Fase rápida

Até 5 tentativas com backoff exponencial: base de 2 s, dobrando a cada tentativa, com teto de 60 s e jitter de 50% a 100%. As cinco tentativas cabem em algumas dezenas de segundos. Cobre uma instabilidade curta.
2

Cauda longa

Se a fase rápida se esgotar, a entrega volta cerca de 30 min, 2,5 h e 24,5 h depois. Cada retorno roda uma fase rápida nova. Cobre uma queda medida em horas.
O jitter existe para que várias entregas não voltem em bloco contra um endpoint que acabou de se recuperar. Depois do último horário, a entrega vira dead e para de ser tentada. A partir daí, reconcilie pelo log de entregas abaixo.
Dimensione seu cache de deduplicação para 48 h. A última retentativa chega cerca de 24,5 h depois da primeira e carrega o mesmo X-PrismaPay-Delivery. Se a sua chave expirar antes disso, você processa o mesmo crédito duas vezes.
Cada tentativa é assinada de novo, com um t= novo. Não recuse uma retentativa só porque o timestamp dela é mais recente que o da primeira. O agendamento é contado, não relojoado: ele vive no banco e avança um passo por retentativa. Nem uma reinicialização nossa nem uma janela sem processamento consomem um horário que a entrega não usou.

Log de entregas

Tudo que tentamos enviar para você, para achar o que nunca chegou e reprocessar do seu lado.
status aceita um único valor. Repetir o parâmetro não faz um filtro “ou”: o valor extra é descartado em silêncio. Para varrer dois estados, faça duas consultas. A query também é estrita: qualquer parâmetro fora desta tabela devolve 422 invalid_request.

Campos

failureReason assume um destes valores:
Você consegue reconstruir o envelope completo a partir de uma linha do log: { version: 1, eventId, type: eventType, seq, time: createdAt, accountId, data: payload }.

Paginação

As linhas voltam da mais recente para a mais antiga, ordenadas por seq. Passe o nextCursor da resposta anterior para buscar a próxima página. nextCursor: null significa fim da lista. Não existe um campo hasMore separado: o cursor é o sinal.

Polling incremental

O seq vem de uma sequência compartilhada entre todos os parceiros. O seu fluxo tem buracos: seq ordena os seus eventos, não os conta. Duas entregas simultâneas também podem gravar fora de ordem, então uma linha com seq menor pode aparecer pouco depois de você já ter passado dela. Ao consultar de forma incremental, reprocesse uma sobreposição, os últimos minutos ou algumas centenas de seq, em vez de parar na marca que você guardou. Uma varredura completa para trás não sofre desse efeito.
Um accountId que você não gerencia, suspenso ou revogado responde 404 account_not_found, igual a qualquer outra leitura por conta. Você nunca recebe uma página vazia que pareça “nada foi enviado”.

Configuração

A URL de destino e o whsec_... são cadastrados pela PrismaPay junto com a credencial. Para trocar a URL ou girar o segredo, fale com o time.

Requisitos do seu endpoint

Redirecionar o endpoint de webhook é a causa silenciosa mais comum de entregas que viram dead. Um redirecionamento automático de http para https, ou de domínio raiz para www, quebra a entrega. Cadastre a URL final.