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:
IP Descriçã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 Evento Quando 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:
Owem tenta novamente com backoff exponencial
Após múltiplas falhas, o webhook pode ser desativado
Você será notificado para corrigir
Responda sempre em menos de 3 segundos . Processe os dados de forma
assíncrona (fila, background job).
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 rápido, processe depois
Responda 200 imediatamente e processe o evento em background.
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 
