Webhooks

Webhooks let Cashramp push real-time updates to your server whenever a transaction changes state—success, cancellation, chargeback, and more.

Event Payload

Every webhook is an HTTPS POST with a JSON body shaped like:

Field	Type	Description
event_type	string	Machine-readable name of the event (see list below).
data	object	Event-specific payload.

Common event_type Values

Event	Trigger
payment_request.updated	Payment request moves through created → picked_up → completed / canceled.
onchain_tx.updated	On-chain withdrawal status changes.
chargeback.initiated	A dispute or MoMo reversal is opened on a completed payment.

---

Example Payloads

Payment request

{
  "event_type": "payment_request.updated",
  "data": {
    "id": "VHlwZXM6OkNhc2hyYW1wOjpBUEk6Ok1lcmNoYW50UGF5bWVudFJlcXVlc3QtOGI0OTdmZTYtOTljYS00MDQwLTkzNWQtMTY2OGJhNGUyNzU2",
    "reference": "test_ref_022",
    "status": "completed",
    "customer": {
      "id": "TWVyY2hhbnRDdXN0b21lci0xZmNiYTgzNi01MDNmLTQyMjYtYjgzYy02NzIzNjMxNDM0YWI=",
      "email": "[email protected]",
      "country": "GH",
      "currency": "GHS"
    },
    "p2p_payment": {
      "id": "UDJQUGF5bWVudC0xOGRmNmJiNC1hNmQ2LTQyMWUtYjQ0MS04YmFiMmE2YzQ5Yjc=",
      "exchange_rate": "7.95",
      "amount": "159.0",
      "amount_usd": "20.0",
      "fee": "0.3"
    },
    "created_at": "2025-05-02T12:43:40.914Z",
    "payment_link": "https://useaccrue.com/hosted/pay/..."
  }
}

On-chain Tx

{
  "event_type": "onchain_tx.updated",
  "data": {
    "id": "VHlwZXM6Ok9uY2hhaW5UeC1hYzNmODk2Mi1jNzRkLTRmNWMtYTQ5ZC1kYmIzMWM1MDc5Mzc=",
    "address": "TPy5hAiyWeKoUHAnAUSoK8YuqbTx75X8xX",
    "status": "completed",
    "quantity": 1000,
    "fee": 0,
    "symbol": "USDT",
    "network": "TRX",
    "txhash": "8efb22782c0a42047266aa6c3df1cfc60cd3ead4ba31075e5d6fccf833402e24"
  }
}

Chargeback

{
  "event_type": "chargeback.initiated",
  "data": {
    "id": "TWVyY2hhbnRDaGFyZ2ViYWNrLWQ2MGVjMjI3LThhNTYtNDMxNS1hNWQ4LTk3N2JhNmFhNmE3Mw==",
    "status": "pending",
    "reason": "A MoMo reversal was initiated by your customer",
    "payment_request": {
      "id": "VHlwZXM6OkNhc2hyYW1wOjpBUEk6Ok1lcmNoYW50UGF5bWVudFJlcXVlc3QtYmMxYTMzMzktNTM5YS00Y2ZkLWE3ZmEtMTM1MzllZGVhNWQw",
      "reference": "c9b1082d49185da9",
      "amount": 100,
      "currency": "usd"
    }
  }
}

---

Responding to Webhooks

Return 200 OK immediately. Any non-2xx or timeout is treated as a delivery failure, and the event will be retried.

1. Validate – Compare the X-CASHRAMP-TOKEN header to the token in your dashboard.

2. Process – Perform your business logic (credit user, update order, etc.).

---

Best Practices

• Verify the token before trusting the payload—prevents spoofing.

• Log the raw body for audits and easier debugging.

• Keep handlers fast—offload heavy work to background jobs.

• Rotate tokens periodically or immediately on suspicion of compromise.