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:
event_type
string
Machine-readable name of the event (see list below).
data
object
Event-specific payload.
Common event_type
Values
event_type
Valuespayment_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
Responding to Webhooks
Return 200 OK
immediately. Any non-2xx or timeout is treated as a delivery failure, and the event will be retried.
Validate – Compare the
X-CASHRAMP-TOKEN
header to the token in your dashboard.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.
Last updated