Webhook

Os webhooks permitem que seu sistema receba notificações automáticas sobre eventos importantes na plataforma da Pix One. Isso elimina a necessidade de consultar a API constantemente para verificar mudanças de status.

Como Funcionam os Webhooks

​Quando um evento ocorre na Pix One (como uma transação aprovada ou uma nova transação criada), nosso sistema envia uma requisição HTTP POST para uma URL que você definiu, contendo informações detalhadas sobre o evento.

Configuração de Webhooks

Para configurar webhooks, acesse seu painel na Pix One:

1. Navegue até Webhook

2. Insira a URL de destino para receber as notificações

3. Selecione os eventos que deseja monitorar

Sua URL de webhook deve estar acessível publicamente na internet para receber as notificações.

Modelo de Webhook

A Pix One utiliza o seguinte modelo padrão de envio para webhooks:

{
  "id": "string",
  "type": "transaction",
  "transaction": "url",
  "data": {
    "object": {
      "id": "string",
      "ip": "string | null",
      "fee": {
        "netAmount": "number",
        "fixedAmount": "number",
        "estimatedFee": "number",
        "spreadPercentage": "number"
      },
      "pix": {
        "qrcode": "string"
      },
      "items": [
        {
          "id": "integer",
          "title": "string",
          "saleId": "integer",
          "physical": "boolean",
          "quantity": "integer",
          "createdAt": "date-time",
          "productId": "integer | null",
          "unitPrice": "number",
          "productImg": "integer | null",
          "externalRef": "integer | null",
          "productDesc": "integer | null",
          "productFile": "integer | null",
          "productName": "integer | null",
          "productPage": "integer | null",
          "productType": "integer | null",
          "productBanner": "integer | null"
        }
      ],
      "amount": "number",
      "boleto": {
        "url": "string",
        "barcode": "string",
        "paidAt": "date-time | null"
      },
      "refundedAt": "date-time | null",
      "status": "paid | processing | pending | approved | refused | chargedback | refunded | cancelled | chargeback",
      "customer": {
        "id": "string",
        "name": "string",
        "email": "string",
        "phone": "string",
        "address": {
          "id": "integer",
          "fee": "number",
          "saleId": "integer",
          "street": "string",
          "tracking": "integer | null",
          "steetCity": "string",
          "streetState": "string",
          "streetNumber": "string",
          "streetCountry": "integer | null",
          "streetZipCode": "string",
          "tracking_code": "integer | null",
          "tracking_status": "string",
          "streetComplement": "string",
          "streetNeighborhood": "string"
        },
        "document": {
          "type": "string",
          "number": "string"
        }
      },
      "delivery": {
        "status": "string",
        "createdAt": "date-time",
        "trackingCode": "string | null"
      },
      "metadata": "object | null",
      "secureId": "string",
      "companyId": "string",
      "tenant": "string",
      "traceable": "boolean",
      "paidAmount": "number",
      "externalRef": "string | null",
      "postbackUrl": "string",
      "installments": "integer",
      "paymentMethod": "string",
      "refusedReason": "string | null",
      "splits": [
        {
          "Type": "object"
        }
      ],
      "refunds": [
        {
          "Type": "object"
        }
      ],
      "refundedAmount": "number",
      "createdAt": "date-time"
    }
  }
}

Eventos Disponíveis

A Pix One oferece os seguintes eventos para webhooks:

Evento	Descrição
transaction.paid	Um pagamento foi confirmado
transaction.processing	Uma transação está em processamento
transaction.pending	Uma transação está pendente
transaction.approved	Uma transação foi aprovada
transaction.refused	Uma transação foi recusada
transaction.chargedback	Uma transação sofreu chargeback
transaction.refunded	Uma transação foi reembolsada
transaction.cancelled	Uma transação foi cancelada

Política de Retentativas

Se seu endpoint retornar um código diferente de 200 ou não responder dentro de 10 segundos, a Pix One seguirá uma política de retentativas:

• 1ª retentativa: 1 minuto após a falha

• 2ª retentativa: 5 minutos após a falha

• 3ª retentativa: 30 minutos após a falha

• 4ª retentativa: 2 horas após a falha

• 5ª retentativa: 6 horas após a falha

Após cinco tentativas sem sucesso, o webhook será marcado como falho e não será reenviado automaticamente.