Event Processing

Status

When a client subscribes to webhooks, Qolo will ping the endpoint configured for the subscription to check its availability before saving. If a successful response is received within 5 seconds, the webhook subscription will be set to active. If not, the subscription will be set to inactive. Clients must ensure connectivity before subscribing to webhooks. A common issue is that clients subscribe with an endpoint that is not responsive, then fix the responsiveness and hope their subscription is active.

If your webhook subscription was never active and is now set to inactive, please contact Qolo to activate it.

Retry

Upon successfully subscribing to webhooks, Qolo will begin sending webhook events according to the subscription. If a successful response is not received from the client’s servers within 5 seconds of a webhook being posted to a client, Qolo will retry sending the webhook up to 6 times at different time intervals.

Signature

Each event posted to a client’s system will include a hashed payload in the request header under the field x-qolo-signature. Clients should verify the hash using SHA-256 with a library or algorithm of their choice. The result of this verification should match the x-qolo-signature sent in the header. This step is crucial to confirm that the request originated from Qolo.

Example:

// Create HMAC using the secret

var crypto = require('crypto');

const hmac = crypto.createHmac('sha256', '<CLIENT SECRET>');
  
const payload = '<TRANSACTION PAYLOAD IN RAW FORMAT>';
  
// Update the HMAC with the payload and get the digest in hexadecimal format
const computedHash = hmac.update(payload).digest('hex');

// the value will be the same as the x-qolo-signature
console.log(computedHash);

Recommendation

Subscribe to the classes of each event to receive updates on all aspects of a particular activity, especially those related to cards, transfers, transactions, and persons.

Event	Description
card	Receive updates on all card-related events, including PIN changes, fulfillment, status updates, and replacements.
person	Receive updates on all person-related events, such as changes to person verification.
company	Receive updates on all person-related events, such as changes to company verification.
account	Receive updates on all account-related events, such as changes in status.
bankeft.credit	Receive updates on all ACH credit-related events, such as reversals and returns.
bankeft.debit	Receive updates on all ACH debit-related events, such as reversals and returns.
transfer	Receive updates on all transfer-related events, such as the success of a transfer.

Review the different types of request codes that may accompany each event type here.