Webhooks

Cadastre a URL em Integrações → Webhooks e escolha os eventos. A cada evento, a Auryon faz um POST com um JSON assinado. Você pode ter até 20 webhooks por conta.

Libere o acesso ao produto em transaction.paid, nunca em transaction.created. Uma transação criada ainda não foi paga.

O envelope

Todo evento chega no mesmo envelope. O objeto do evento fica em data.object:

{
  "id": "evt_01JXEXEMPLO0000000000000000",
  "api_version": "2026-06-15",
  "type": "transaction.paid",
  "created": 1781524800,
  "livemode": true,
  "data": {
    "object": {
      "id": "txn_exemplo_123",
      "status": "APROVADA",
      "payment_method": "PIX",
      "payment_method_detail": null,
      "amount": "19900",
      "shipping_amount": "0",
      "currency": "BRL",
      "installments": 1,
      "identifier": "SEU-PEDIDO-123",
      "metadata": {
        "origem": "exemplo"
      },
      "offer_code": "ABC12345",
      "product": {
        "name": "Produto de exemplo"
      },
      "offer": {
        "name": "Oferta principal"
      },
      "customer": {
        "name": "Comprador de Exemplo",
        "email": "comprador@exemplo.test"
      },
      "created_at": "2026-06-15T12:00:00.000Z",
      "paid_at": "2026-06-15T12:00:00.000Z"
    }
  }
}

Campo	O que é
id	o identificador do evento (evt_…). O mesmo em todas as retentativas e reenvios.
api_version	a versão do formato: hoje 2026-06-15
type	o evento (lista completa)
created	quando o fato aconteceu, em segundos Unix
livemode	true em produção
data.object	o objeto do evento: venda, assinatura, saque, afiliação, etapa do funil…

shipping_amount é o frete de produto físico, já contido em amount ("0" sem frete).

Cabeçalhos

Cabeçalho	Conteúdo
X-Auryon-Signature	t=<timestamp>,v1=<assinatura> (dois v1= durante uma rotação). Veja Assinatura.
X-Auryon-Timestamp	o mesmo t da assinatura, em segundos Unix
X-Auryon-Event-Id	o id do evento
X-Auryon-Event-Type	o type
X-Auryon-Webhook-Id	qual dos seus webhooks recebeu
X-Auryon-Api-Version	a versão do envelope, igual ao api_version do corpo
X-Auryon-Delivery-Attempt	o número da tentativa (1 a 6)
User-Agent	Auryon369-Webhook/1.0

Responder

• Responda 2xx em até 30 segundos. Qualquer outro status, ou timeout, conta como falha.
• Redirecionamentos (3xx) não são seguidos: cadastre a URL final.
• Responda rápido e processe depois (numa fila), para não estourar os 30 segundos.

Retentativas e saúde

• Até 6 tentativas por evento: imediata, 30 s, 5 min, 30 min, 5 h e 24 h (cerca de 30 horas no total).
• Quando uma entrega esgota as 6 tentativas, o webhook fica degradado e as tentativas passam a uma por dia. Um sucesso o devolve a ativo.
• Depois de 7 dias degradado sem nenhum sucesso, o webhook fica desativado. Ele não volta sozinho: reative-o no painel, no botão Reativar.
• Desativado, nada é enviado. Eventos que acontecem enquanto o webhook está desativado não são guardados e não podem ser reenviados depois. Entregas que já estavam na fila voltam a sair quando você reativa.
• Um destino lento não atrasa os outros: cada webhook tem a própria fila, e os eventos de um mesmo webhook saem na ordem em que aconteceram.

Idempotência

O mesmo evento pode chegar mais de uma vez, por retentativa ou reenvio manual. Guarde o id do evento (X-Auryon-Event-Id) e processe cada um uma vez só.

Painel: teste, entregas e reenvio

• Enviar teste mostra, antes de enviar, o corpo exato que vai chegar, e o envia assinado com a sua chave, com dados fictícios. É uma tentativa só: se falhar, não entra nas retentativas nem conta para a saúde do webhook. Só eventos já disponíveis podem ser testados, e só em webhook ativo.
• Entregas lista cada envio com o status, a resposta do seu servidor e a tentativa. “O que enviamos” mostra o corpo exato da última tentativa e a assinatura que foi junto.
• Reenviar manda de novo uma entrega, com o mesmo id de evento. Exige o webhook ativo; uma entrega que está saindo naquele instante não é reenviada em dobro. O conteúdo de cada envio fica guardado por 30 dias; depois disso, o reenvio não é mais possível.

Formato legado

Webhooks no formato Legado recebem o corpo da plataforma anterior, com o token no corpo e sem assinatura. Esse formato está depreciado: veja API legada.