Webhooks

Webhooks — Faturas Internas

Receba notificações quando o status de uma fatura interna mudar para PAID ou EXPIRED. O webhook não é disparado para outros estados.

Quando o Webhook é Enviado

Quando a fatura é paga

status: "PAID"

Quando a fatura expira

status: "EXPIRED"

Configuração

Headers do Webhooktext

Método: POST
Content-Type: application/json
User-Agent: Invoice-Webhook/1.0
Timeout: 10 segundos

Payload do Webhook

Interface TypeScripttypescript

interface InternalInvoiceWebhook {
  id: string;                    // UUID da cobrança
  code: string;                  // Código único de 8 caracteres
  amount: number;                // Valor da cobrança
  status: "PENDING" | "PAID" | "CANCELLED" | "EXPIRED";
  description: string;           // Descrição da cobrança
  due_date: string | null;       // Data de vencimento (ISO 8601) ou null
  created_at: string;            // Data de criação (ISO 8601)
  updated_at: string;            // Data de atualização (ISO 8601)
}

Exemplos de Payload

Fatura Pagajson

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "code": "ABC12345",
  "amount": 100.50,
  "status": "PAID",
  "description": "Pagamento de serviços",
  "due_date": "2026-02-15T10:00:00Z",
  "created_at": "2026-01-28T10:00:00Z",
  "updated_at": "2026-01-28T15:30:00Z"
}

Fatura Expiradajson

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "code": "ABC12345",
  "amount": 100.50,
  "status": "EXPIRED",
  "description": "Pagamento de serviços",
  "due_date": "2026-01-27T10:00:00Z",
  "created_at": "2026-01-20T10:00:00Z",
  "updated_at": "2026-01-28T16:00:00Z"
}

Campos do Payload

Campo	Tipo	Descrição
`id`	`string (UUID)`	ID único da fatura
`code`	`string`	Código único de 8 caracteres da fatura
`amount`	`number`	Valor da cobrança em BRL
`status`	`string`	Novo status: PAID ou EXPIRED
`description`	`string`	Descrição da fatura
`due_date`	`string \| null`	Data de vencimento em ISO 8601 ou null se não configurada
`created_at`	`string (ISO 8601)`	Data de criação
`updated_at`	`string (ISO 8601)`	Data da última atualização

Implementação de Exemplo

Node.js + Expressjavascript

app.post('/webhooks/internal-invoice', (req, res) => {
  const { id, code, amount, status, description, due_date } = req.body;
  
  // Responda imediatamente com 200
  res.status(200).json({ received: true });

  setImmediate(() => {
    if (status === 'PAID') {
      // Fatura paga — libere o serviço
      liberarServico(id, code, amount);
    } else if (status === 'EXPIRED') {
      // Fatura expirada — notifique ou cancele o pedido
      cancelarPedido(id, code);
    }
  });
});

Observações Importantes

O webhook é enviado apenas quando o status muda para PAID ou EXPIRED
O timeout é de 10 segundos — responda rapidamente
Configure o webhook_url ao criar a fatura com POST /v1/internal-invoice
O campo due_date pode ser null se não houver vencimento configurado