Webhooks

Celar uses webhooks to notify your system in real time whenever a payin, payout, or withdrawal changes status.
This allows PSPs to update balances, trigger settlement flows, or handle exceptions without polling.

How It Works

• Celar sends an HTTPS POST request to your registered webhook_url whenever an event is triggered.
• Each delivery includes a full JSON payload.
• Failed deliveries are retried up to 3 times with exponential backoff.
• Delivery history (status codes, timestamps) can be fetched via the API.

⚠️ Your server must expose a public HTTPS endpoint to receive webhook events.

Supported Events

Event Name	Description
payin.confirmed	A payin was detected on-chain and confirmed.
payin.settled	Payin successfully routed to PSP and treasury wallets.
payin.settlement_failed	Payin was confirmed but final settlement to PSP wallet failed.
payin.failed	Payin blocked due to KYT or validation failure.
payin.mismatched	Payin received but amount did not match the expected value.
payout.sent	A payout was executed and broadcast to the blockchain.
payout.failed	A payout attempt failed (insufficient funds, routing error, or KYT block).
withdraw.sent	A withdrawal request was successfully executed.
withdraw.failed	A withdrawal attempt failed.

Example Payload

{
  "event": "payin.settled",
  "payment_id": "payin_abc123",
  "psp_amount": "95.00",
  "treasury_fee": "5.00",
  "tx_hash": "0xdeadbeefcafefeed1234567890abcdef1234567890abcdef1234567890abcdef",
  "chain": "base",
  "token": "USDC",
  "timestamp": "2025-09-26T12:34:56Z"
}

Webhook Endpoints

Set Webhook URL

You can register or update your webhook URL either through the dashboard (Settings → API Keys) or via the API:

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

Get Webhook Delivery Logs

Retrieve a full history of webhook delivery attempts for a payment_id or batch_id.
Each record shows the delivery status, attempt count, response code/body, and the exact payload Celar sent.

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

Best Practices

• Respond with 200 OK within 5 seconds; otherwise Celar retries delivery.
• Log payloads for reconciliation in case retries or manual recovery are required.
• Idempotent handling → Always treat webhook events as possibly duplicated.