Cashonrails Webhooks

Webhooks allow your application to receive real-time notifications about events that occur in your Cashonrails account. This document explains how to configure and use webhooks effectively with the Cashonrails platform.

Configure Webhook URL

On your dashboard navigate to the Settings > API Keys and Webhook section, where you will be able to configure your test & live webhook URLs and all other necessary API and webhook parameters.

Webhook Security

Authorization Header

All webhook requests include an Authorization header with a Bearer Token containing your webhook key:

Authorization: Bearer {{webhook_key}}

Payload Signature

For added security, each webhook includes a payload signature in the headers:

payloadsignature: HMAC 512 payload signature

We strongly recommend verifying this signature to ensure the webhook came from Cashonrails and wasn’t tampered with during transmission.

Collection Webhook

When the final status of a transaction is confirmed, you’ll receive a webhook with the following format:

Headers

Authorization: Bearer {{webhook_key}}
payloadsignature: HMAC 512 payload signature

Body

{
  "event": "transaction",
  "data": {
    "id": 13787,
    "business_id": 46,
    "currency": "NGN",
    "amount": "100",
    "trx": "202503311338792079044",
    "reference": "COR-kxkv7lsvpaktxuhhuiytn",
    "ip_address": "144.24.227.131",
    "channel": "banktransfer",
    "type": "transaction",
    "domain": "live",
    "fee": "1.6",
    "customer_id": 18021,
    "plan": null,
    "requested_amount": "100",
    "status": "success",
    "card_attempt": 0,
    "gateway": "vfd",
    "created_at": "2025-03-31T13:38:34.000000Z",
    "paid_at": "2025-03-31 13:38:34",
    "customerinfo": {
      "id": 18021,
      "account_name": "Ayomide Owolana",
      "first_name": "Ayomide",
      "last_name": "Owolana",
      "email": "ayomideowolana1@gmail.com",
      "phone": null,
      "customer_code": "CUS_qgfaagpfpbu8cms",
      "domain": "live",
      "status": "active",
      "created_at": "2025-03-21T20:02:17.000000Z"
    }
  },
  "payment_account": null,
  "sender_details": {
    "sender_account_name": "CASHONRAILS INFRASTRUCTURE LIMITED",
    "sender_account_number": "0114314606",
    "sender_bank_code": "090286",
    "sender_narration": "FRM CASHONRAILS INFRASTRUCTURE LIMITED|COR | Test",
    "sessionId": "090286250331133812177637260116",
    "trx": "202503311338792079044"
  }
}

Payout Webhook

When the final status of a transfer is confirmed, you’ll receive a webhook with the following format:

Headers

Authorization: Bearer {{webhook_key}}
payloadsignature: HMAC 512 payload signature

Body

{
  "status": "00",
  "event": "payout",
  "currency": "NGN",
  "amount": "50",
  "fee": "25",
  "account_name": "OLUWANIFEMI AYOMIDE OWOLANA",
  "account_number": "9113146539",
  "bank_code": "100004",
  "bank_name": "OPAY",
  "narration": "test",
  "trx": "2025032514551037062256",
  "reference": "COR-2025032514551037062256",
  "sessionid": "090110250325145519844017129603",
  "domain": "live",
  "statusMessage": "success",
  "note": null,
  "timestamp": "2025-03-25T14:55:17.000000Z"
}

Webhook Response

Your server should respond with a 200 OK HTTP status code to acknowledge receipt of the webhook. If Cashonrails doesn’t receive a 200 response, we will attempt to retry the webhook delivery according to our retry schedule.

Resend Webhook

Webhooks for both confirmed transactions and transfers can be manually resent from the dashboard. This is useful for testing your webhook integration or recovering from missed webhook events.

Best Practices for Webhook Implementation

1. Verify the signature to ensure the webhook came from Cashonrails
2. Process idempotently to handle potential duplicate webhook deliveries
3. Respond quickly with a 200 status code, then process the webhook asynchronously
4. Store raw webhook data for debugging and troubleshooting purposes
5. Monitor webhook failures to detect integration issues early
6. Implement proper error handling to gracefully handle unexpected payload formats

Testing Webhooks

You can test your webhook integration using test mode in your Cashonrails dashboard. Test webhooks will have the domain field set to test instead of live.