Webhooks -- Overview

Webhooks allow your application to receive real-time notifications about events on the Owem Pay platform. When an event occurs, Owem Pay sends an HTTP POST to the registered URL.

How It Works

1. Register a webhook URL in your account
2. When an event occurs (e.g., PIX received), Owem Pay sends an HTTP POST to your URL
3. Your application processes the notification and responds with a 2xx status (200, 201, or 204)

Available Events

Event	Description
pix.received	PIX received in the account (cash-in confirmed)
pix.completed	PIX transfer sent successfully (cash-out)
pix.failed	PIX transfer failed
pix.refund	PIX refund processed
pix.med	MED notification received from BACEN

Security

Each notification includes security headers for validation:

Header	Description
X-Owem-Signature	HMAC-SHA256 signature of the payload
X-Owem-Timestamp	Timestamp of the delivery (ISO 8601)
X-Owem-Event-Id	Unique event ID (for deduplication)
X-Owem-Event-Type	Event type (e.g., pix.received)

Validating the Signature

Validate the signature to ensure the notification was sent by Owem Pay:

const crypto = require('crypto');

function validateWebhook(payload, timestamp, signature, secret) {
  const message = `${timestamp}.${payload}`;
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Always validate

Never process a webhook without validating the signature. This protects against forged requests.

Retry Policy

If your URL returns a non-2xx status, Owem Pay performs automatic retries:

Attempt	Interval
1st	Immediate
2nd	1 minute
3rd	5 minutes
4th	30 minutes
5th	2 hours

After 5 unsuccessful attempts, the event is marked as failed and will not be automatically resent.

Idempotency

Your application must be idempotent: if it receives the same event more than once (identified by X-Owem-Event-Id), it should process it without duplicating effects.

Endpoint Requirements

• The URL must use HTTPS
• Must respond with a 2xx status within 5 seconds
• The response body is ignored

Next Steps

• Register Webhook -- create, list, and remove webhooks
• Event Payloads -- examples of each event type