Skip to main content

​
Overview

Webhooks allow you to receive automatic notifications when important events happen in your account. Instead of polling, you receive an HTTP POST with the event data.

​
Source IPs

All webhooks are sent exclusively from these IPs:
IPDescription
34.134.50.53Owem Server 1
35.238.101.57Owem Server 2
Configure your firewall to accept connections only from these IPs on your webhook endpoint.

​
Configure a Webhook

​
Step 1: Create Endpoint

Create an HTTPS endpoint on your server that:
  • Accepts POST requests
  • Responds 2xx within 3 seconds
  • Is publicly accessible
// Example with Express.js
app.post("/webhooks/owem", (req, res) => {
  const event = req.body

  // Process event asynchronously
  processEvent(event)

  // Respond immediately with 200
  res.status(200).send("OK")
})

​
Step 2: Register at 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://mysite.com/webhooks/owem",
    "authHeader": "Bearer my_secret_token"
  }'

​
Available Events

EventWhen it occurs
pix_in:qrcode_paidQR Code payment confirmed
pix_in:creditedCredit via PIX key
pix_in:refunded_processingPIX IN refund initiated
pix_out:processingPIX OUT registered/confirmed
pix_out:refunded_processingPIX OUT return
med:receivedMED received
*All events

​
Payload Structure

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

​
Validate Authenticity

Always validate received webhooks: 
app.post("/webhooks/owem", (req, res) => {
  // 1. Validate source IP
  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. Validate authHeader (if configured)
  const authHeader = req.headers["authorization"]
  if (authHeader !== "Bearer my_secret_token") {
    return res.status(401).send("Unauthorized")
  }

  // 3. Process event
  const event = req.body
  processEvent(event)

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

​
Idempotency

Owem may resend webhooks in case of failure. Implement idempotency to avoid duplicate processing: 
const processedEvents = new Set()

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

  // Check if already processed
  if (processedEvents.has(eventKey)) {
    console.log("Event already processed:", eventKey)
    return
  }

  // Mark as processed
  processedEvents.add(eventKey)

  // Process event
  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
  }
}
In production, use a database to control already processed events.

​
Retries and Backoff

If your endpoint doesn’t respond 2xx within 3s:
  1. Owem retries with exponential backoff
  2. After multiple failures, the webhook may be disabled
  3. You’ll be notified to fix it
Always respond in less than 3 seconds. Process data asynchronously (queue, background job).

​
Manage Webhooks

​
List configurations

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

​
Temporarily disable

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

​
Reactivate

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

​
Best Practices

Respond 200 immediately and process the event in background.
Always validate webhook origin before processing.
Events may be resent. Avoid duplicate processing.
Endpoint must mandatorily use HTTPS.
Configure alerts to detect when webhooks stop arriving.

​
Next Steps

API Reference

Complete endpoint documentation

Reconciliation

Use the Ledger as source of truth