Signature Verification

Webhook Signatures

Each webhook in COS is signed with a standard HMAC with SHA256 hash. This provides an added layer of protection from replay attacks. Without a signature present in the webhook, an attacker could potentially intercept a valid payload and re-transmit it. However, since the event timestamp is part of the signature, it is not possible to modify either the timestamp or the signature without also invalidating the signature.

📘

Old Timestamps

If you receive an event with an old timestamp it is recommended your application discard or flag it. The recommended tolerance between timestamp and time of delivery will vary by your application's requirements, but should generally be less than 20 minutes. Special consideration for situations where there has been an extended outage between either party is also recommended.

The signature can be found in the event's request header.

cos-signature:t:2019-04-02T11:33:26.6672036-04:00,
v1:adT6JQ7y+fbL2a0uq4infc6VOX+VPyJizRTMSz158Vs=

All COS signatures are version 1 (v1). Any other schemes besides v1 should ignored.
The signature is a standard HMAC with SHA256 hash.
COS generates the timestamp and signature each time we send an event to your endpoint. If COS retries an event, after a previous failure, we generate a new signature and timestamp for the new delivery attempt.

Validating the Signature

  1. Extract the timestamp and signature from the cos-signature header
  2. Concatenate the timestamp with the event body with a period in between the two values (as illustrated below).
  3. Compute an HMAC with the SHA256 hash function. Use the signing secret (provided by your COS integration team) as the key and use the string created in step #2, as the message. Also be sure to base64 encode the computed hash value.
  4. Compare the hash generated in step #3 with the signature extracted from the cos-signature header. If the hash and signature match this is a valid request from COS.
  5. Compare the timestamp to the time received. If the difference exceeds your tolerance for accepting messages, you can reject the message or flag it for further review.
2019-04-02T11:33:26.6672036-04:00.{"id":"123","eventName":"Core.Customer.Email.Added","partnerId":"123","createdAt":"2019-04-02T11:33:26-04:00","resources":["core/v1/cm/customers/123"]}

Below is a Node.js script which illustrates how a webhook signature would typically be validated.

const crypto = require('crypto');

function validateSignature(header, payload, signingSecret) {
                let headerParts = header.split(',');
                let timestamp = headerParts[0].replace('t:', '');
                let signature = headerParts[1].trim().replace('v1:', '');

                let secret_buffer = Buffer.from(signingSecret, 'base64');              
                let hmac = new crypto.createHmac('sha256', secret_buffer);

                let hmac_digest = hmac.update(`${timestamp}.${payload}`, 'binary').digest('base64');
                console.log(hmac_digest);

                return hmac_digest === signature;
}


let payload = '{"id":"e7ead744-d6ff-4521-863d-abab0176f849","eventName":"Core.Transaction.Completed","status":0,"partnerId":"d6b4c661-b38a-46a3-8963-a9a40131eacf","createdAt":"2020-04-28T18:45:14.57-04:00","resources":["core/v1/transactions/6aa7e3b2-3c85-4647-aa6f-abab0176e18b"],"details":[{"transactionId":"6aa7e3b2-3c85-4647-aa6f-abab0176e18b","transactionCode":"Account Transfer","debitSubAccount":"2058112745","debitMasterAccount":"2058112745","debitResult":"OK","creditSubAccount":"2101120877","creditMasterAccount":"2101120877","creditResult":"OK","rail":"Internal","railId":"0","amount":"100"}]}';
let signatureHeader = 't:2020-04-28T18:45:15.6360965-04:00, v1:MvGXdx1O1P8+YjWglbmxAxkrAgVlMglSPpCzsR/Ly/w=';
let secret = 'uVdwwB9HIFZ+5/8nmta5PXu6p1kxZcQmXPCNBRhiVNuKNBhIgth8MvmlD7FYoVfHOmcpHO5QYN/3HHnJ+6TO6Q==';

let result = validateSignature(signatureHeader, payload, secret);

console.log(result);

Did this page help you?