Skip to main content

Callbacks (Provider Webhooks)

Payment gateway providers send notifications to the system when payment statuses change. These notifications are processed asynchronously.

Callback Endpoints​

Kobana​

POST /api/callbacks/kobana

Signature Header: X-Kobana-Signature: sha256=<hex>

Received events:

  • pix.register.confirmed / error / failed / requested
  • pix.paid
  • bank_billet.register.confirmed / error / failed / requested
  • bank_billet.paid

Pagar.me​

POST /api/callbacks/pagarme

Signature Header: x-hub-signature: sha256=<hex>

Received events:

  • order.* (paid, payment_failed, created, canceled, closed, updated)
  • charge.* (paid, payment_failed, refunded, pending, processing, etc.)
  • card.* (created, updated, deleted, expired)

Processing Flow​

Receives POST from provider
  → Validates HMAC-SHA256 signature
  → Checks idempotency key (ignores duplicates)
  → Creates Callback record (status=pending)
  → Enqueues job for async processing
  → Returns 200 immediately

Async Processing​

Worker processes the queue
  → Routes to provider handler
  → Maps provider status to internal status
  → Updates payment record
  → Creates event for notification
  → Updates Callback (status=completed)

Security​

  • Signature validation: HMAC-SHA256 with timing-safe comparison
  • Idempotency: Unique key [provider, idempotencyKey] prevents duplication
  • Retries: Maximum of 5 attempts with exponential backoff
  • Retention: Failed callbacks kept for 7 days

Callback Record​

Each received callback is recorded with:

  • Source provider
  • Idempotency key
  • Complete headers and payload
  • Processing status
  • Number of attempts
  • Result or error message