Webhook API

Manage webhook configurations and logs for real-time event notifications

The Webhook API provides endpoints to manage webhook configurations, view delivery logs, and resend failed webhook notifications. Receive real-time notifications about account events, transactions, and PIX operations.

Key Features

• Event Notifications: Real-time notifications for account events
• Delivery Logs: Complete history of webhook deliveries
• Failed Delivery Management: Resend failed webhooks
• Flexible Configuration: Configure URLs and event filters per webhook

Available Endpoints

Webhook Management

• Create Webhook - Register a new webhook
• List Webhooks - View all configured webhooks
• Update Webhook - Modify webhook configuration
• Delete Webhook - Remove a webhook

Webhook Monitoring

• List Webhook Logs - View webhook delivery history
• List Webhook Resend Logs - View resend attempt history
• Resend Webhook - Manually resend a failed webhook

Authentication

All Webhook API endpoints require:

• Bearer Token: Include in the Authorization header
• HMAC Signature: Include in the hmac header for API audience requests

Webhook Events

The system sends webhooks for the following events:

Transaction Events

• transaction.created - New transaction initiated
• transaction.completed - Transaction successfully completed
• transaction.failed - Transaction failed
• transaction.cancelled - Transaction cancelled

PIX Events

• pix.received - PIX payment received
• pix.sent - PIX payment sent
• pix.qrcode.paid - QR code payment received
• pix.chargeback.requested - Chargeback requested
• pix.chargeback.approved - Chargeback approved

Account Events

• account.balance.updated - Account balance changed
• account.status.changed - Account status changed

PIX Key Events

• pixkey.created - New PIX key registered
• pixkey.deleted - PIX key removed
• pixkey.claim.received - Ownership claim received

Webhook Delivery

Delivery Mechanism

• HTTP POST request to configured URL
• JSON payload
• Timeout: 30 seconds
• Retry policy: Up to 3 attempts with exponential backoff

Expected Response

Your webhook endpoint should:

• Return HTTP 200-299 status code
• Respond within 30 seconds
• Process requests idempotently (same event may be sent multiple times)

Retry Schedule

If delivery fails:

1. Immediate: First retry after 1 minute
2. Second: Retry after 10 minutes
3. Third: Retry after 1 hour

Webhook Security

Best Practices

1. Verify Signatures: Always verify the webhook signature in the X-Webhook-Signature header
2. Use HTTPS: Configure HTTPS URLs only
3. Validate Events: Check event types before processing
4. Idempotency: Use transaction IDs to prevent duplicate processing
5. Respond Quickly: Return 200 OK immediately, process asynchronously
6. Log Everything: Keep logs of received webhooks

Webhook Logs

Log Retention

• Delivery logs are retained for 90 days
• Resend logs are retained for 30 days

Log Fields

• Webhook ID
• Event type
• Delivery status (success/failed)
• HTTP status code
• Response time
• Timestamp
• Retry attempts
• Error messages (if failed)