Cashramp
  • Introduction
    • Getting Started
    • Payment Rails
    • API Endpoints
    • Authentication
    • Webhooks
    • Integration Guide
    • SDKs
  • Hosted Ramp
    • Overview
    • Deposits
    • Withdrawals
    • Cancel Payment
  • Direct Ramp
    • Overview
    • Ramp Quotes
    • Deposits
    • Withdrawals
  • Onchain Ramp
    • Overview
    • On-Off Ramp
  • Cashramp API
    • Queries
    • Customers
    • Payment Methods
    • Withdraw Onchain
    • Virtual Bank Accounts
Powered by GitBook
On this page
  • Event Payload
  • Common event_type Values
  • Example Payloads
  • Responding to Webhooks
  • Best Practices
  1. Introduction

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

{
  "event_type": "payment_request.updated",
  "data": {
    "id": "VHlwZXM6OkNhc2hyYW1wOjpBUEk6Ok1lcmNoYW50UGF5bWVudFJlcXVlc3QtOGI0OTdmZTYtOTljYS00MDQwLTkzNWQtMTY2OGJhNGUyNzU2",
    "reference": "test_ref_022",
    "status": "completed",
    "customer": {
      "id": "TWVyY2hhbnRDdXN0b21lci0xZmNiYTgzNi01MDNmLTQyMjYtYjgzYy02NzIzNjMxNDM0YWI=",
      "email": "engineering@useaccrue.com",
      "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/..."
  }
}
{
  "event_type": "onchain_tx.updated",
  "data": {
    "id": "VHlwZXM6Ok9uY2hhaW5UeC1hYzNmODk2Mi1jNzRkLTRmNWMtYTQ5ZC1kYmIzMWM1MDc5Mzc=",
    "address": "TPy5hAiyWeKoUHAnAUSoK8YuqbTx75X8xX",
    "status": "completed",
    "quantity": 1000,
    "fee": 0,
    "symbol": "USDT",
    "network": "TRX",
    "txhash": "8efb22782c0a42047266aa6c3df1cfc60cd3ead4ba31075e5d6fccf833402e24"
  }
}
{
  "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.

PreviousAuthenticationNextIntegration Guide

Last updated 18 days ago