PT

Documentação

Eventos e webhooks

Cada mudança de estado de um pagamento gera um evento que chega por webhook ao servidor do dono e pode ser lido por 30 dias com GET /v1/events; a lista de tipos é aberta, então ignore os que você não conhece.

Como são entregues

Os webhooks são para o servidor do dono. O agente não os recebe: consulta o pagamento com GET /v1/spends/{id}.
Cada evento traz id, sequence (inteiro crescente por ambiente), livemode e a versão da API. É entregue pelo menos uma vez: deduplique por id e descarte os de sequence menor que um já aplicado.
A assinatura vai no cabeçalho Nouron-Signature com o formato t=<segundos>,v1=<hex>: um HMAC-SHA256 do texto <t>.<corpo cru> com o segredo whsec_… do destino, com tolerância de 300 segundos. Durante uma rotação chegam duas assinaturas v1; basta que uma coincida.
Responda 2xx assim que ler a entrega e processe depois. Se não, ela é repetida 8 vezes em cerca de 24 horas.
GET /v1/events serve de reserva: guarda os últimos 30 dias.

Um evento

{  "id": "evt_<32 hex>",  "object": "event",  "type": "spend.settled",  "api_version": "2026-10-01",  "created": "2026-10-09T14:03:24Z",  "livemode": false,  "sequence": 42,  "agent_id": "agt_<32 hex>",  "data": {    "object": {      "id": "spd_<32 hex>",      "object": "spend",      "status": "settled"    }  }}

Os tipos de evento

Hoje há 32 tipos de evento: 19 da primeira fase, 11 de auditoria e 2 reservados.

A lista de tipos é aberta: podem aparecer tipos novos sem mudar a versão. Ignore os que não conhece e responda 2xx.

Os tipos spend.created e approval.expired da versão anterior não existem mais.

Pagamentos

spend.pending_approval

O pagamento aguarda a aprovação do dono (T2, T10).

objeto: spend · quem vê: agente e dono · fase: primeira fase

spend.approved

Passou pelas regras; limite reservado, ainda não enviado (T3, T4).

objeto: spend · quem vê: agente e dono · fase: primeira fase

spend.declined

Não foi pago: uma regra, o dono ou uma mudança entre passos (T1, T5, T6, T11).

objeto: spend · quem vê: agente e dono · fase: primeira fase

spend.processing

Foi enviado ao trilho; sem resultado ainda (T9).

objeto: spend · quem vê: agente e dono · fase: primeira fase

spend.settled

Pagamento confirmado; o objeto traz settlement.receipt_id (T14).

objeto: spend · quem vê: agente e dono · fase: primeira fase

spend.failed

Foi aprovado e o trilho recusou; nenhum dinheiro foi movido (T15).

objeto: spend · quem vê: agente e dono · fase: primeira fase

spend.expired

A aprovação venceu sem resposta (T7, T12).

objeto: spend · quem vê: agente e dono · fase: primeira fase

spend.cancelled

O agente cancelou antes do envio (T8, T13).

objeto: spend · quem vê: agente e dono · fase: primeira fase

spend.refunded

Devolução posterior a settled (T17).

objeto: spend · quem vê: agente e dono · fase: reservado

spend.disputed

Reclamação aberta sobre um pagamento liquidado (T18).

objeto: spend · quem vê: agente e dono · fase: reservado

Aprovações

approval.requested

Foi criada uma aprovação pendente para o dono.

objeto: approval · quem vê: só o dono · fase: primeira fase

approval.decided

O dono aprovou ou recusou; traz o canal e a referência do aprovador.

objeto: approval · quem vê: só o dono · fase: primeira fase

Depósito

funding.awaiting_deposit

Aguardando um depósito na bolsa de prática.

objeto: funding · quem vê: só o dono · fase: primeira fase

funding.deposit_received

Chegou um depósito.

objeto: funding · quem vê: só o dono · fase: primeira fase

funding.converted

Um depósito foi convertido em dólares digitais de prática.

objeto: funding · quem vê: só o dono · fase: primeira fase

funding.failed

Um depósito não pôde ser concluído.

objeto: funding · quem vê: só o dono · fase: primeira fase

Carteira

wallet.low_balance

O saldo caiu abaixo do limite de aviso.

objeto: wallet · quem vê: só o dono · fase: primeira fase

Regras

policy.updated

Foi publicada uma nova versão das regras; traz version e hash.

objeto: policy · quem vê: agente e dono · fase: primeira fase

policy.change_requested

Foi pedida uma mudança que AFROUXA regras; vale a partir de effective_at, a menos que seja cancelada.

objeto: policy_change · quem vê: só o dono · fase: auditoria

Agentes

agent.paused

Um agente foi pausado (o dono, a pausa de emergência ou a plataforma).

objeto: agent · quem vê: agente e dono · fase: primeira fase

agent.resumed

Um agente foi reativado.

objeto: agent · quem vê: agente e dono · fase: primeira fase

agent.created

Um agente foi criado.

objeto: agent · quem vê: só o dono · fase: auditoria

agent.archived

Um agente foi arquivado (suas chaves são revogadas).

objeto: agent · quem vê: só o dono · fase: auditoria

Chaves

api_key.created

Uma chave de API foi criada (nunca inclui o segredo).

objeto: api_key · quem vê: só o dono · fase: auditoria

api_key.rotated

Uma chave foi rotacionada; a antiga convive até grace_period_ends_at.

objeto: api_key · quem vê: só o dono · fase: auditoria

api_key.revoked

Uma chave foi revogada.

objeto: api_key · quem vê: só o dono · fase: auditoria

Destinos

destination.added

Um destino permitido foi adicionado (pode haver espera antes de valer).

objeto: destination · quem vê: só o dono · fase: auditoria

destination.removed

Um destino permitido foi removido.

objeto: destination · quem vê: só o dono · fase: auditoria

Avisos

webhook_endpoint.created

Um destino de webhook foi criado.

objeto: webhook_endpoint · quem vê: só o dono · fase: auditoria

webhook_endpoint.paused

Um destino de webhook foi pausado por falhas repetidas.

objeto: webhook_endpoint · quem vê: só o dono · fase: auditoria

notification_channel.added

Um canal de avisos (e-mail, Telegram...) foi adicionado.

objeto: notification_channel · quem vê: só o dono · fase: auditoria

Sistema

webhook.test

Evento de teste enviado a pedido do dono; não é preciso se inscrever.

objeto: webhook_test · quem vê: só o dono · fase: primeira fase