Webhooks

Webhooks play an important part in your integration of Cashramp. They are how we'll notify you of any changes that happen to the transactions you initiate, such as a user cancelling, no agents being available, or a successful payment.

Cashramp webhook payload structure

All Cashramp webhook payloads follow the same structure:

• an event_type field describing the type of event

• a data object whose contents vary with the type of event.

Here are sample payloads for the different kinds of webhook notifications you might receive:

Payment request webhook

{
  "event_type": "payment_request.updated",
  "data": {
    "id": "VHlwZXM6OkNhc2hyYW1wOjpBUEk6Ok1lcmNoYW50UGF5bWVudFJlcXVlc3QtOGI0OTdmZTYtOTljYS00MDQwLTkzNWQtMTY2OGJhNGUyNzU2",
    "reference": "test_ref_022",
    "status": "completed",
    "customer": {
      "id": "TWVyY2hhbnRDdXN0b21lci0xZmNiYTgzNi01MDNmLTQyMjYtYjgzYy02NzIzNjMxNDM0YWI=",
      "email": "[e-mail]",
      "wallet_address": null,
      "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",
    "onchain_amount: "0.0",
    "onchain_address": null,
    "onchain_cryptocurrency": null,
    "onchain_network": null,
    "onchain_txhash": null,
    "onchain_fee": "0.01",
    "payment_link": "http://localhost:8080/hosted/pay/VHlwZXM6OkNhc2hyYW1wOjpBUEk6Ok1lcmNoYW50UGF5bWVudFJlcXVlc3QtOGI0OTdmZTYtOTljYS00MDQwLTkzNWQtMTY2OGJhNGUyNzU2",
  }
}

Onchain withdrawal webhook

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

Fiat payout webhook

{
    "event_type": "fiat_payout.updated",
    "data": {
        "id": "VHlwZXM6OlBheW1lbnQtOWQ3M2RmNjMtMmM1YS00ZjZhLWE2NWUtMWZmMjcxNDkwOGZl",
        "payment_type": "withdrawal",
        "amount_usd": 200,
        "amount": 178600,
        "reference": "e937f7140bdd77f9552d6a17b12ef02f",
        "status": "completed"
    }
}

Chargeback initiated webhook

{
    "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"
        }
    }
}

You should respond to our webhook events immediately with 200 OK HTTP status code. Any other response code will be treated as a failed delivery of the event.

Remember to return 200 OK before starting any long-running tasks. Long-running tasks will lead to a request timeout.

Best practices

Webhook Token Verification

Your webhook URL is publicly accessible, and bad actors can send fake data to it in an attempt to trick your application into releasing value to them.

Webhook events sent from Cashramp carry a X-CASHRAMP-TOKEN header. You should check that the header's value matches your webhook token before processing the event.