Pular para o conteúdo principal

​
Visão Geral

Webhooks permitem que você receba notificações automáticas quando eventos importantes acontecem na sua conta. Em vez de fazer polling, você recebe um POST HTTP com os dados do evento.

​
IPs de Origem

Todos os webhooks são enviados exclusivamente destes IPs:
IPDescrição
34.134.50.53Servidor Owem 1
35.238.101.57Servidor Owem 2
Configure seu firewall para aceitar conexões apenas desses IPs no endpoint de webhook.

​
Configurar um Webhook

​
Passo 1: Criar Endpoint

Crie um endpoint HTTPS no seu servidor que:
  • Aceite requisições POST
  • Responda 2xx em até 3 segundos
  • Esteja acessível publicamente
// Exemplo com Express.js
app.post("/webhooks/owem", (req, res) => {
  const event = req.body

  // Processa o evento de forma assíncrona
  processEvent(event)

  // Responde imediatamente com 200
  res.status(200).send("OK")
})

​
Passo 2: Registrar na Owem

curl -X POST "https://api.owem.com.br/v4/i/webhooks/config" \
  -u "API_KEY:API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "event": ["*"],
    "targetUrl": "https://meusite.com/webhooks/owem",
    "authHeader": "Bearer meu_token_secreto"
  }'

​
Eventos Disponíveis

EventoQuando ocorre
pix_in:qrcode_paidPagamento de QR Code confirmado
pix_in:creditedCrédito via chave PIX
pix_in:refunded_processingEstorno de PIX IN iniciado
pix_out:processingPIX OUT registrado/confirmado
pix_out:refunded_processingDevolução de PIX OUT
med:receivedMED recebido
*Todos os eventos

​
Estrutura do Payload

{
  "webhookId": "wh_abc123",
  "userId": "usr_abcdef12",
  "accountId": "987654321000",
  "event": "pix_out:processing",
  "object": {
    "id": "E123456789...",
    "externalId": "PAG-001",
    "status": "succeeded",
    "grossAmount": 100.0,
    "feeAmount": 0.08,
    "netAmount": 100.08,
    "endToEndId": "E123456789...",
    "createdAt": 1766523042000,
    "payer": { ... },
    "receiver": { ... }
  }
}

​
Validar Autenticidade

Sempre valide os webhooks recebidos: 
app.post("/webhooks/owem", (req, res) => {
  // 1. Validar IP de origem
  const allowedIPs = ["34.134.50.53", "35.238.101.57"]
  const clientIP = req.ip || req.headers["x-forwarded-for"]

  if (!allowedIPs.includes(clientIP)) {
    return res.status(403).send("Forbidden")
  }

  // 2. Validar authHeader (se configurado)
  const authHeader = req.headers["authorization"]
  if (authHeader !== "Bearer meu_token_secreto") {
    return res.status(401).send("Unauthorized")
  }

  // 3. Processar evento
  const event = req.body
  processEvent(event)

  res.status(200).send("OK")
})

​
Idempotência

A Owem pode reenviar webhooks em caso de falha. Implemente idempotência para evitar processamento duplicado: 
const processedEvents = new Set()

async function processEvent(event) {
  const eventKey = `${event.event}:${event.object.id}`

  // Verifica se já processou
  if (processedEvents.has(eventKey)) {
    console.log("Evento já processado:", eventKey)
    return
  }

  // Marca como processado
  processedEvents.add(eventKey)

  // Processa o evento
  switch (event.event) {
    case "pix_in:qrcode_paid":
      await handlePixInPaid(event.object)
      break
    case "pix_out:processing":
      await handlePixOut(event.object)
      break
    case "med:received":
      await handleMed(event.object)
      break
  }
}
Em produção, use um banco de dados para controlar eventos já processados.

​
Retries e Backoff

Se seu endpoint não responder 2xx em até 3s:
  1. Owem tenta novamente com backoff exponencial
  2. Após múltiplas falhas, o webhook pode ser desativado
  3. Você será notificado para corrigir
Responda sempre em menos de 3 segundos. Processe os dados de forma assíncrona (fila, background job).

​
Retenção de Dados

Os dados dos webhooks enviados são armazenados na Owem por 7 dias. Após esse período, os registros são automaticamente removidos. Utilize esse período para debugging, reconciliação e troubleshooting de entregas.

​
Gerenciar Webhooks

​
Listar configurações

curl -X GET "https://api.owem.com.br/v4/i/webhooks/config/me" \
  -u "API_KEY:API_SECRET"

​
Desativar temporariamente

curl -X POST "https://api.owem.com.br/v4/i/webhooks/config/{configId}/deactivate" \
  -u "API_KEY:API_SECRET"

​
Reativar

curl -X POST "https://api.owem.com.br/v4/i/webhooks/config/{configId}/activate" \
  -u "API_KEY:API_SECRET"

​
Boas Práticas

Responda 200 imediatamente e processe o evento em background.
Sempre valide a origem do webhook antes de processar.
Eventos podem ser reenviados. Evite processamento duplicado.
O endpoint deve obrigatoriamente usar HTTPS.
Configure alertas para detectar quando webhooks param de chegar.

​
Próximos Passos

API Reference

Documentação completa dos endpoints

Conciliação

Use o Ledger como fonte de verdade