SimPayDocs

    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

    Webhook Monitoring

    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)