Webhooks

Celar uses webhooks to notify your system in real time whenever a payment-related operation changes state.
This allows you to update balances, trigger settlement flows, or handle exceptions without polling.

Webhooks are delivered as HTTPS POST requests to your registered endpoint.

How Webhooks Work

• Celar sends an HTTPS POST request to your registered webhook_url when an event occurs
• Each delivery contains a full JSON payload describing the event
• Failed deliveries are retried up to 3 times with exponential backoff
• Delivery logs can be retrieved via the API for debugging and reconciliation

⚠️ Your webhook endpoint must be publicly accessible over HTTPS.

Supported Events

Celar emits events across pay-ins, payouts, withdrawals, refunds, and transfers.

Pay-in Events

Event Name	Description
payin.confirmed	Pay-in detected and confirmed on-chain
payin.settled	Pay-in successfully settled
payin.settlement_failed	Pay-in confirmed but settlement failed
payin.failed	Pay-in failed due to validation or compliance checks
payin.mismatched	Received amount does not match expected value
payin.underpaid	Received amount is lower than expected

Payout Events

Event Name	Description
payout.pending	Payout created and awaiting execution
payout.sent	Payout executed and broadcast on-chain
payout.failed	Payout could not be completed

Withdrawal Events

Event Name	Description
withdraw.sent	Withdrawal executed successfully
withdraw.failed	Withdrawal attempt failed

Refund Events

Event Name	Description
refund.sent	Refund executed successfully
refund.failed	Refund attempt failed

Transfer Events

Event Name	Description
transfer.settled	Transfer completed successfully
transfer.failed	Transfer execution failed
transfer.underpaid	Transfer underpaid by sender

Example Webhook Payload

{
  "event": "transfer.settled",
  "payment_id": "transfer_abc123",
  "tx_hash": "0xdeadbeefcafefeed1234567890abcdef1234567890abcdef1234567890abcdef",
  "chain": "base",
  "token": "USDC",
  "amount": "3.922",
  "timestamp": "2026-01-05T12:34:56Z"
}

Payload fields vary slightly by event type but always include event, payment_id, and timestamp.

Managing Webhook URLs

Set or Update Webhook URL

You can configure your webhook URL via the dashboard or using the API.

curl --request PATCH \
  --url https://api.sandbox.celar.io/api/v1/set_webhook \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "webhook_url": "https://example.com/webhooks/celar"
  }'

Webhook Delivery Logs

Retrieve webhook delivery attempts for a specific payment_id.

curl --request GET \
  --url https://api.sandbox.celar.io/api/v1/payments/<payment_id>/webhooks \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>'

Each log entry includes delivery status, attempt count, response code, and payload.

Best Practices

• Respond with 200 OK within 5 seconds to acknowledge receipt
• Treat webhook deliveries as idempotent (events may be retried)
• Log webhook payloads for reconciliation and debugging
• Do not rely on webhooks as the sole source of truth — always reconcile via APIs when needed