> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axnpay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks de transacao

> Eventos da AXNPAY para o merchant e validacao de assinatura.

## Visao geral

A AXNPAY envia webhooks assinados para notificar mudancas de status de transacao e saque.

No fluxo de cobranca:

1. A AXNPAY recebe a confirmacao do processador interno.
2. A AXNPAY atualiza a transacao.
3. A AXNPAY envia o webhook normalizado para o merchant.

Headers enviados:

* `X-Webhook-Event`
* `X-Webhook-Signature` (HMAC SHA-256 em hexadecimal)

## Eventos disponiveis

* `transaction.created`
* `transaction.completed`
* `transaction.failed`
* `transaction.reversed`
* `transaction.cancelled`
* `transaction.chargeback`
* `cashout.created`
* `cashout.processing`
* `cashout.completed`
* `cashout.failed`
* `cashout.reversed`

## Payload base

```json theme={null}
{
  "event": "transaction.completed",
  "timestamp": "2026-04-01T22:15:40.000Z",
  "data": {
    "id": 115,
    "referenceId": "e1de94c1-5692-48e1-a334-24b367ad76ff",
    "status": "COMPLETED",
    "type": "CASHIN",
    "checkoutSessionId": "checkout_sess_abc123",
    "paymentIntentId": "payment_abc123",
    "trackingParameters": {
      "utm_source": "meta_ads",
      "utm_medium": "cpc",
      "utm_campaign": "black_friday",
      "utm_content": "criativo_1",
      "utm_term": "checkout"
    },
    "tracking_parameters": {
      "utm_source": "meta_ads",
      "utm_medium": "cpc",
      "utm_campaign": "black_friday",
      "utm_content": "criativo_1",
      "utm_term": "checkout"
    },
    "utm_source": "meta_ads",
    "utm_medium": "cpc",
    "utm_campaign": "black_friday"
  }
}
```

<Info>
  Quando a cobranca for criada com `tracking_parameters`, a AXNPAY repassa esses dados no webhook dentro de `trackingParameters`, `tracking_parameters` e tambem nos campos planos `utm_*`.
</Info>

## Validacao da assinatura (Node.js)

```js theme={null}
import crypto from "crypto";

function validateWebhookSignature(rawBody, signature, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const sigBuf = Buffer.from(signature || "", "utf8");
  const expBuf = Buffer.from(expected, "utf8");
  if (sigBuf.length !== expBuf.length) return false;
  return crypto.timingSafeEqual(sigBuf, expBuf);
}
```

## Requisitos do seu endpoint

1. Aceitar `POST application/json`.
2. Responder `2xx` rapidamente.
3. Persistir o evento antes de processar regra pesada.
4. Ignorar evento duplicado com base em `event + referenceId + timestamp` ou chave equivalente.

## Endpoints de gerenciamento de webhook

Esses endpoints usam autenticacao JWT de usuario do painel, nao `sk_live_prod_*`:

* `GET /v1/user/webhooks/events`
* `POST /v1/user/webhooks`
* `GET /v1/user/webhooks`
* `GET /v1/user/webhooks/:id`
* `PATCH /v1/user/webhooks/:id`
* `DELETE /v1/user/webhooks/:id`
* `POST /v1/user/webhooks/:id/revalidate`

<Info>
  Se voce estiver usando checkout de cartao, veja tambem [Cartao](/card-checkout).
</Info>