Hooks

O que são hooks?

Hooks permitem que você execute código em momentos específicos do fluxo de pagamento. O pagamentos.dev oferece dois tipos de hooks unificados:

Lifecycle hooks — disparam automaticamente após operações de API bem-sucedidas (criar, consultar, atualizar, listar, cancelar).
Webhook hooks — disparam quando eventos assíncronos chegam via webhook (pagamento realizado, cobrança vencida, etc).

Você registra os hooks diretamente na configuração da instância Pagamentos:

import {
  Pagamentos,
  mercadopago,
  onCobrancaCreated,
  onWebhookEvent
} from 'pagamentos'

const pg = new Pagamentos({
  providers: [mercadopago({ accessToken: '...' })],
  hooks: [
    // Lifecycle hook
    onCobrancaCreated(async (evt) => {
      console.log('Cobrança criada:', evt.output.id)
    }),

    // Webhook hook
    onWebhookEvent('pagamento.realizado', async (event) => {
      console.log('Pagamento recebido:', event.data)
    })
  ]
})

Lifecycle hooks

Os lifecycle hooks capturam eventos que acontecem imediatamente após uma chamada de API retornar com sucesso. Eles são ideais para logging, auditoria, sincronização com seu banco de dados ou disparo de ações internas.

Evento de lifecycle

Cada hook recebe um objeto LifecycleEvent com as seguintes propriedades:

Propriedade	Descrição
`provider`	Nome do provedor (ex: `'mercadopago'`, `'abacatepay'`).
`resource`	Recurso operado (ex: `'clientes'`, `'cobrancas'`, `'checkout'`).
`operation`	Operação executada (ex: `'create'`, `'get'`, `'update'`, `'list'`, `'delete'`, `'cancel'`).
`input`	Dados de entrada da operação.
`output`	Dados de retorno da operação.

Hooks por operação

Você pode escutar eventos específicos de cada recurso e operação:

Clientes

import {
  onClienteCreated,
  onClienteRetrieved,
  onClienteUpdated,
  onClienteListed,
  onClienteDeleted
} from 'pagamentos'

const pg = new Pagamentos({
  providers: [/* ... */],
  hooks: [
    onClienteCreated(async (evt) => {
      await db.clientes.insert(evt.output)
    })
  ]
})

Cobranças

import {
  onCobrancaCreated,
  onCobrancaRetrieved,
  onCobrancaUpdated,
  onCobrancaListed,
  onCobrancaCancelled
} from 'pagamentos'

const pg = new Pagamentos({
  providers: [/* ... */],
  hooks: [
    onCobrancaCreated(async (evt) => {
      await enviarEmailDeConfirmacao(evt.output.cliente.email)
    })
  ]
})

Checkout

import { onCheckoutCreated } from 'pagamentos'

const pg = new Pagamentos({
  providers: [/* ... */],
  hooks: [
    onCheckoutCreated(async (evt) => {
      analytics.track('checkout_iniciado', { url: evt.output })
    })
  ]
})

Hooks por recurso (genéricos)

Se quiser escutar todas as operações de um recurso, use os hooks de recurso:

import { onCliente, onCobranca, onCheckout } from 'pagamentos'

const pg = new Pagamentos({
  providers: [/* ... */],
  hooks: [
    onCobranca(async (evt) => {
      // Dispara para create, get, update, list, cancel
      await auditLog.register({
        provider: evt.provider,
        operation: evt.operation,
        cobrancaId: evt.output?.id
      })
    })
  ]
})

Hook genérico customizado

Para casos mais específicos, use onLifecycleEvent para filtrar manualmente por recurso e operação:

import { onLifecycleEvent } from 'pagamentos'

const pg = new Pagamentos({
  providers: [/* ... */],
  hooks: [
    onLifecycleEvent('cobrancas', 'create', async (evt) => {
      // Mesmo comportamento de onCobrancaCreated
      await cache.invalidate(`cliente:${evt.output.cliente.id}`)
    })
  ]
})

Webhook hooks

Enquanto os lifecycle hooks reagem a ações que você realiza via API, os webhook hooks reagem a eventos que acontecem no provedor (ex: cliente pagou, boleto venceu, assinatura foi renovada).

Eventos canônicos

O pagamentos.dev normaliza os eventos de diferentes provedores em nomes canônicos. Os principais eventos disponíveis são:

pagamento.realizado
pagamento.falhou
cobranca.vencida
cobranca.cancelada
cobranca.disputada
assinatura.ativada
assinatura.cancelada
assinatura.renovada
transferencia.envio
transferencia.falhou
desembolso.envio
desembolso.falhou

Usando `onWebhookEvent`

Registre um handler para um evento específico:

import { onWebhookEvent } from 'pagamentos'

const pg = new Pagamentos({
  providers: [/* ... */],
  hooks: [
    onWebhookEvent('pagamento.realizado', async (event) => {
      event.event  // 'pagamento.realizado'
      event.data   // { cobranca: Cobranca; cliente?: Cliente }
      event.raw    // payload original do provedor

      await db.pedidos.update({
        cobrancaId: event.data.cobranca.id,
        status: 'pago'
      })
    })
  ]
})

Aliases curinga

Você pode usar padrões curinga para escutar múltiplos eventos de uma vez:

import { onWebhookEvent } from 'pagamentos'

const pg = new Pagamentos({
  providers: [/* ... */],
  hooks: [
    // Todos os eventos de pagamento
    onWebhookEvent('pagamento.*', async (event) => {
      if (event.event === 'pagamento.realizado') {
        await liberarAcesso(event.data.cobranca.id)
      } else if (event.event === 'pagamento.falhou') {
        await notificarCliente(event.data.cobranca.cliente)
      }
    }),

    // Todos os eventos de cobrança
    onWebhookEvent('cobranca.*', async (event) => {
      await auditLog.register({ tipo: event.event, dados: event.data })
    }),

    // Catch-all: qualquer evento
    onWebhookEvent('*', async (event) => {
      console.log('Evento recebido:', event.event, event.data)
    })
  ]
})

Para mais detalhes sobre como receber e validar webhooks, consulte a página dedicada a Webhooks.

Exemplo prático combinado

Aqui está um exemplo completo que combina lifecycle hooks e webhook hooks para gerenciar o ciclo de vida de uma cobrança:

import {
  Pagamentos,
  mercadopago,
  onCobrancaCreated,
  onWebhookEvent
} from 'pagamentos'

const pg = new Pagamentos({
  providers: [mercadopago({
    accessToken: process.env.MP_ACCESS_TOKEN,
    signingSecret: process.env.MP_SIGNING_SECRET
  })],
  hooks: [
    // 1. Lifecycle: quando criamos a cobrança
    onCobrancaCreated(async (evt) => {
      await db.cobrancas.create({
        idempotencyKey: crypto.randomUUID(),
        id: evt.output.id,
        valor: evt.input.valor,
        status: 'pendente',
        cliente: evt.input.cliente
      })

      await enviarEmailDePixGerado({
        email: evt.input.cliente.email,
        qrCode: evt.output.pix.qrCode
      })
    }),

    // 2. Webhook: quando o provedor notifica que foi pago
    onWebhookEvent('pagamento.realizado', async (event) => {
      await db.cobrancas.update({
        id: event.data.cobranca.id,
        status: 'pago',
        pagoEm: new Date()
      })

      await liberarProduto(event.data.cobranca.id)
      await enviarComprovante(event.data.cliente?.email)
    }),

    // 3. Webhook: quando a cobrança vence
    onWebhookEvent('cobranca.vencida', async (event) => {
      await db.cobrancas.update({
        id: event.data.cobranca.id,
        status: 'vencido'
      })

      await enviarLembreteDeVencimento(event.data.cobranca.cliente)
    })
  ]
})

Neste exemplo:

O lifecycle hook onCobrancaCreated garante que toda cobrança criada seja salva no banco de dados local e que o cliente receba o e-mail com o QR Code.
O webhook hook pagamento.realizado atualiza o status no banco e libera o produto assim que o pagamento é confirmado pelo provedor.
O webhook hook cobranca.vencida trata cobranças não pagas dentro do prazo.

Dicas e boas práticas

Hooks são síncronos ou assíncronos: handlers podem retornar void ou Promise<void>. O SDK aguarda a conclusão dos hooks assíncronos.
Evite lógica pesada nos hooks: se o processamento for longo, considere enfileirar em um background job para não bloquear a resposta da API ou do webhook.
Idempotência em webhooks: provedores podem enviar o mesmo evento múltiplas vezes. Verifique se o evento já foi processado usando o event.id.
Tipagem forte: os hooks de webhook são totalmente tipados. Ao usar eventos canônicos, o TypeScript infere corretamente o formato de event.data.

Fundamentos

Métodos de Pagamento

Funcionalidades

O que são hooks?

Lifecycle hooks

Evento de lifecycle

Hooks por operação

Clientes

Cobranças

Checkout

Hooks por recurso (genéricos)

Hook genérico customizado

Webhook hooks

Eventos canônicos

Usando `onWebhookEvent`

Aliases curinga

Exemplo prático combinado

Dicas e boas práticas

​O que são hooks?

​Lifecycle hooks

​Evento de lifecycle

​Hooks por operação

​Clientes

​Cobranças

​Checkout

​Hooks por recurso (genéricos)

​Hook genérico customizado

​Webhook hooks

​Eventos canônicos

​Usando onWebhookEvent

​Aliases curinga

​Exemplo prático combinado

​Dicas e boas práticas

O que são hooks?

Lifecycle hooks

Evento de lifecycle

Hooks por operação

Clientes

Cobranças

Checkout

Hooks por recurso (genéricos)

Hook genérico customizado

Webhook hooks

Eventos canônicos

Usando `onWebhookEvent`

Aliases curinga

Exemplo prático combinado

Dicas e boas práticas