Webhooks

Webhooks ou notificações são chamadas que o cel_payments faz na sua aplicação. Ou seja, você prepara um script para ler um conteúdo JSON que enviamos a você e fazer alguma rotina no seu sistema.

Eles são usados para que você possa manter o seu sistema sincronizado com o nosso em caso de mudanças que ocorrem após ou fora do fluxo direto da API.
Exemplo: um boleto gerado pode ser pago a qualquer momento. Para que seu sistema possa atualizar o status de pagamento quando for pago, te enviaremos o webhook baaspay-transaction-updateStatus com as informações atualizadas.

Regras

Sua url deverá responder em até 5 segundos
Não seguimos redirecionamentos. Enviamos o conteúdo para url exata que tiver sido cadastrada. Se você possuir https, por exemplo, coloque já a url com https no webhooks.
Se sua url não responder com um código 2xx, tentaremos enviar o webhook novamente mais 5 vezes em intervalos progressivos durante aproximadamente 48 horas. Após isso, não tentaremos mais.
A estrutura da API suporta apenas uma URL de webhook por conjunto de conta e subcontas. A URL de webhook deve ser cadastrada na conta master, e todas as subcontas herdarão essa configuração. Não é possível configurar URLs de webhook distintas por subconta.

Segurança

Não confie em webhooks enviados por IPs que não estejam listados abaixo:

❗️
Atenção:
Esses IPs podem ser alterados sem aviso prévio)
IPS de produção: 54.232.59.251 e 54.232.204.133
IP de sandbox: 54.207.173.93

Tipos de webhooks disponíveis:

Atualmente, oferecemos duas opções de rotas para você realizar o cadastro das suas URLs que receberão os webhooks.

Independentemente da rota escolhida para fazer o cadastro, os eventos, as regras e a estrutura dos dados (payload) que você vai receber no seu sistema são exatamente os mesmos. A diferença está apenas no caminho que você usa para registrar a URL.

Opção 1: Via Cadastro de Webhooks do BaaS

Esta é a estrutura mais recente e oficial para o provisionamento de webhooks. Todas as novas integrações ou manutenções de URLs utilizem este método.

Para cadastrar utilizando este novo fluxo, utilize o endpoint Cadastrar Webhook - JWT.

Entity	Descrição
baaspay-transaction-updateStatus	Será enviado quando uma transação tiver seu status de pagamento alterado. Vai conter todos os dados da entidade Transaction.
baaspay-contract-accepted	Será enviado quando o cliente aceitar o contrato digital. Vai conter todos os dados da entidade Charge ou Subscription, variando do tipo de cobrança.
baaspay-addTransaction	Será enviado quando uma transação for adicionada em uma assinatura. Vai conter todos os dados da entidade Transaction.
baaspay-update-invoice	Será enviado quando houver informações de atualização do status de nota fiscal
baaspay-chargeback-update	Será enviado quando uma abertura de disputa for criada no sistema. Vai conter todos os dados da entidade Chargeback, além de conter alguns dados da entidade Transaction e PaymentBill.

1. Webhook `baaspay-transaction-updateStatus`

Objetivo: Informar sobre a atualização de uma transação.

Payload: Charge

{
  "tenantId": "******",
  "body": {
    "confirmHash": "892b25b529884691111feae273799e96",
    "transaction": {
      "myId": "pay-69f879d6ac0357.26139136",
      "status": "captured",
      "value": 12999
    },
    "charge": {
      "galaxPayId": 11,
      "status": "active"
    }
  },
  "entity": "baaspay-transaction-updateStatus",
  "createTimestamp": "2026-05-04T09:54:49.2407321",
  "status": "UPDATE"
}

Payload: Subscription

{
  "tenantId": "******",
  "body": {
    "confirmHash": "1bc74d635a6da707ea2cfaff71304749",
    "Transaction": {
      "myId": "pay-69f879de7eacb2.79252590",
      "status": "captured"
    },
    "Subscription": {
      "myId": "pay-69f879e1190672.39307375",
      "status": "active"
    }
  },
  "entity": "baaspay-transaction-updateStatus",
  "createTimestamp": "2026-05-04T09:54:49.2407321",
  "status": "UPDATE"
}

2. Webhook `baaspay-contract-accepted`

Objetivo: Notificar sobre a aceitação de um contrato.

Payload: Charge

{
  "tenantId": "******",
  "body": {
    "confirmHash": "575b370243467249d9321895174571e8",
    "Charge": {
      "myId": "pay-69f879e69b4876.84623712",
      "status": "active"
    }
  },
  "entity": "baaspay-contract-accepted",
  "createTimestamp": "2026-05-04T09:54:49.2407321",
  "status": "ACCEPTED"
}

Payload: Subscription

{
  "tenantId": "******",
  "body": {
    "confirmHash": "3a41aaa621c4783026ce352681e6154c",
    "Subscription": {
      "myId": "pay-69f879ed35cb96.38324803",
      "status": "active"
    }
  },
  "entity": "baaspay-contract-accepted",
  "createTimestamp": "2026-05-04T09:54:49.2407321",
  "status": "ACCEPTED"
}

3. Webhook `baaspay-update-invoice`

Objetivo: Alertar sobre atualizações em faturas.

Payload: Charge

{
  "tenantId": "******",
  "body": {
    "confirmHash": "5aa4dc6f42b127a05fb538e26293fbb4",
    "Transaction": {
      "myId": "pay-69f879fb8c5162.41143324",
      "status": "captured"
    }
  },
  "entity": "baaspay-update-invoice",
  "createTimestamp": "2026-05-04T09:54:49.2407321",
  "status": "UPDATE"
}

Payload: Subscription

{
  "tenantId": "******",
  "body": {
    "confirmHash": "d68ea0ef79e7affed93b1ca5de6b1668",
    "Transaction": {
      "myId": "pay-69f87a01399679.65880962",
      "status": "captured"
    },
    "Subscription": {
      "myId": "pay-69f87a036ba9a5.48398388",
      "status": "active"
    }
  },
  "entity": "baaspay-update-invoice",
  "createTimestamp": "2026-05-04T09:54:49.2407321",
  "status": "UPDATE"
}

4. Webhook `baaspay-subscription-addTransaction`

Objetivo: Alertar sobre a criação de uma transação em uma assinatura.

Payload: Subscription

{
  "tenantId": "******",
  "body": {
    "confirmHash": "5953f5fba3fea4c54eff6b6a5c89a642",
    "Transaction": {
      "myId": "pay-69f879f3c99545.81258001",
      "status": "captured"
    },
    "Subscription": {
      "myId": "pay-69f879f697f0b8.55179519",
      "status": "active"
    }
  },
  "entity": "baaspay-addTransaction",
  "createTimestamp": "2026-05-04T09:54:49.2407321",
  "status": "ADDTRANSACTION"
}

5. Webhook `baaspay-chargeback-update`

Objetivo: Alertar sobre atualizações ocorridas em uma solicitação de chargeback.

Payload: Charge

{
  "tenantId": "******",
  "body": {
    "confirmHash": "13c1b1f795b295a6bb6e6c88b6812489",
    "Chargeback": {
      "galaxPayId": 1,
      "status": "winsDispute",
      "description": "Disputa aberta e aguardando documentação"
    }
  },
  "entity": "baaspay-chargeback-update",
  "createTimestamp": "2026-05-04T09:54:49.2407321",
  "status": "UPDATE"
}

Payload: Subscription

{
  "tenantId": "******",
  "body": {
    "confirmHash": "7756aba399409029b89de82a323c8dce",
    "Chargeback": {
      "galaxPayId": 1,
      "status": "winsDispute",
      "description": "Disputa aberta e aguardando documentação"
    }
  },
  "entity": "baaspay-chargeback-update",
  "createTimestamp": "2026-05-04T09:54:49.2407321",
  "status": "UPDATE"
}

Opção 2: Via rota cel_payments (Legado / Depreciado)

Esta é a rota antiga de cadastro. Ela continua disponível como uma segunda opção e funciona normalmente para o provisionamento, mas entrou em processo de depreciação e será descontinuada no futuro.

Campo	Descrição
transaction.updateStatus	Será enviado quando uma transação tiver seu status de pagamento alterado. Vai conter todos os dados da entidade Transaction.
contract.accepted	Será enviado quando o cliente aceitar o contrato digital. Vai conter todos os dados da entidade Charge ou Subscription, variando do tipo de cobrança.
subscription.addTransaction	Será enviado quando uma transação for adicionada em uma assinatura. Vai conter todos os dados da entidade Transaction.
transaction.updateInvoice	Será enviado quando houver informações de atualização do status de nota fiscal
company.cashOut	Será enviado quando um pagamento Pix ou um Saque/Transferência for realizado no sistema.
company.verifyDocuments	Informações de atualização do status de aprovação de conta
chargeback.update	Será enviado quando uma abertura de disputa for criada no sistema. Vai conter todos os dados da entidade Chargeback, além de conter alguns dados da entidade Transaction e PaymentBill.
company.internalTransfer	Será enviado quando uma transferência interna for realizada. Vai conter todos os dados da entidade Transaction.

Regras

Segurança

Atenção:

Tipos de webhooks disponíveis:

Opção 1: Via Cadastro de Webhooks do BaaS

1. Webhook baaspay-transaction-updateStatus

2. Webhook baaspay-contract-accepted

3. Webhook baaspay-update-invoice

4. Webhook baaspay-subscription-addTransaction

5. Webhook baaspay-chargeback-update

Opção 2: Via rota cel_payments (Legado / Depreciado)

1. Webhook `baaspay-transaction-updateStatus`

2. Webhook `baaspay-contract-accepted`

3. Webhook `baaspay-update-invoice`

4. Webhook `baaspay-subscription-addTransaction`

5. Webhook `baaspay-chargeback-update`