Webhooks

Webhooks (or callbacks) let you automatically receive asynchronous events from Paycashless when important events happen — like when a payment status changes or a virtual account gets credited.

Register your webhook URLs

Webhooks are currently registered when you call APIs via the callbackUrl field.

Webhook Structure

All webhooks have the same payload structure.

event : the name of the event
data : event data specific to the event being sent

Webhook Retries

Always acknowledge a webhook instantly by responding with 2xx, else it will be considered as failed. Failed webhooks are retried with constant backoff for a maximum of 3 times with a delay of 1 minute.

Webhook Security

To ensure you are receiving webhooks from Paycashless we provide Request-Signature and Request-Timestamp in the webhook request header. This is similar to the API signing request, but in reverse. You MUST validate the signature to ensure it’s originating from Paycashless. Webhook signature is signed using HMAC SHA-512 with your API secret as the signing key. Request-Signature and Request-Timestamp will be provided in the webhook request header for you to reconstruct the message for verification. To verify the signature follow the process below:

Step	Action	Description
1	Hash	Take the event data object, stringify the object and hash it with HMAC SHA-512 algorithm using your API secret as the signing key (output should be hex-encoded).
2	Concatenate	Concatenate your full `callback url` exactly as you provided it, `hashed event data`, and `Request-Timestamp` from the header. There are no spaces or other characters between these values. The order of the fields must follow the order stipulated here.
3	Sign	Take the string from the Concatenate step and generate a HMAC SHA-512 signature using your API secret as the signing key.
4	Encode	Take the output of the Sign step and hex-encode it.
5	Verify	Compare the recreated signature with the content of `Request-Signature` header.

The fields used to generate the signature are as follows. If the conditions below are not met, you won’t be able to recreate the Request-Signature header.

Field	Description
Callback URL	Lowercased full URL as provided with the base url and search parameters (e.g. `https://yourwebsite.com/callback/paycashless?notify=all`).
Hashed Body	The event data object, `stringified` and hashed using `HMAC SHA-512` algorithm.
Timestamp	The value gotten from `Request-Timestamp` header.

Study the node.js webhook verification example code below:

verify_webhook_signature.js

import { createHmac, timingSafeEqual } from 'crypto';

function sha512Sign(message, secret) {
  return createHmac('sha512', secret).update(message).digest('hex');
}

export function sha512Verify(data: string, signature: string, key: string): boolean {
  // Generate the expected HMAC
  const expectedSignature = createHmac('sha512', key)
    .update(data, 'utf8')
    .digest('hex');
  
  // Convert both signatures to buffers for timing-safe comparison
  const expectedBuffer = Buffer.from(expectedSignature, 'hex');
  const providedBuffer = Buffer.from(signature, 'hex');
  
  // Ensure both buffers are the same length before comparison
  if (expectedBuffer.length !== providedBuffer.length) {
    return false;
  }
  
  // Use timing-safe comparison to prevent timing attacks
  return timingSafeEqual(expectedBuffer, providedBuffer);
}

// Get the timestamp from 'Request-Timestamp' header
const requestTimestamp = "1704931925543";
const callbackUrl = "https://webhook.site/e1ae9397-bd8d-4327-ad92-da002ea2ef08";
const API_SECRET = "YOUR_API_SECRET"; // replace these with your actual API secret value 
const requestSignature = "f17e737bf9d4a1f46f130126be4b2cdb3109a347565b5f824f9da0a45f14663db899812654d849d731cf825b884e1363a8364c5e622ec86f338a31fdeec7812d";
const event = {"event":"events.payout.succeeded","data":{"amount":10000,"callbackUrl":"https://webhook.site/e1ae9397-bd8d-4327-ad92-da002ea2ef08","confirmationState":"confirmed","currency":"NGN","destinationAccountNumber":"9845648577","destinationBankId":"bank_538ed2056326432ba8e6853b613997bb","emtl":0,"failureCode":null,"failureMessage":null,"fee":1500,"id":"po_dtb9z9jk4fs6vqelh3hb8dxcyscnldpx","liveMode":true,"metadata":{"category":"transfer"},"narration":"zapped","networkSessionId":"090286250606000850470781628636","reference":"trx_fww7b31pbs5mmT3k3qfb47","requiresConfirmation":false,"status":"succeeded","vat":0}}

const bodyHash = sha512Sign(JSON.stringify(event.data), API_SECRET);
const stringToSign = `${callbackUrl}${bodyHash}${timestamp}`;

// Generate the Request-Signature value for the header
const isValid = sha512Verify(stringToSign, requestSignature, API_SECRET);

console.log(isValid ? "Signature is valid" : "Signature is not valid");

Get Started

Online Payments

Register your webhook URLs

Webhook Structure

Webhook Retries

Webhook Security

​Register your webhook URLs

​Webhook Structure

​Webhook Retries

​Webhook Security

Register your webhook URLs

Webhook Structure

Webhook Retries

Webhook Security