Notifications

Overview

As a part of the integration, Kard provides issuers with near real-time notifications via webhooks about important event updates to your rewards program. These notifications are designed in a way where they can be sent directly to your users, enhancing engagement and fostering a more connected, synchronous experience between you and your user base.

Notification webhooks are sent to the designated webhook URL provided by the issuer for each event type, ensuring timely and reliable delivery. To receive notifications, you can self-subscribe to events via API with the Create Subscriptions endpoint. For comprehensive details on payloads and supported event types, please refer to our API Reference section.

We currently support the following event types:

• earnedRewardApproved: receive notifications for when an approved transaction qualifies for a reward
• earnedRewardSettled: receive notifications for when a settled transaction qualifies for a reward

Each notification payload includes:

• Message: A message field with suggested text enabling you to easily send out push notifications to your users.
• Attribution: An attribution field with attribution links enabling you to collect and send attribution related to your notifications. For more details on attribution and how to use these links, visit this page.
• Idempotency: A unique id for each notification, which serves as an idempotency key to ensure consistent and reliable information delivery.

Webhook Authentication

For the notifications webhook, Kard will be posting outbound to a URL provided by the issuer client. This webhook is validated via HMAC signature.

An issuer client will be provided with a webhook key that is used to generate an HMAC of the webhook body. The HMAC is calculated by Kard and will be sent in the notify-signature header. Note that header request attributes are processed as case-insensitive.

To validate, the issuer client should generate the HMAC with the provided key, body and SHA-256 hashing algorithm and compare against the HMAC provided in the header.

The following is a Node.js code recipe that shows one approach to:

1. Stand up a service to ingest a notification webhook
2. Implement HMAC signature verification

Code Recipe: Authenticating, then Ingesting a Notification Webhook

• auth.js: signature verification middleware
• index.js: POST endpoint

# auth.js
const { createHmac } = require("crypto");
const secretKey = issuer_webhook_key; //provided in postman_environment.json
 
const verifyToken = (req, res, next) => {
    // grab HMAC signature from Notify-signature header of request
    const token = req.get("notify-signature");
    if (!token) {
        return res.status(403).send("A token is required for authentication");
    }
    try {
        // cast webhook as string
        const stringRequest = JSON.stringify(req.body);
        // hash using sha256, webhook key, and webhook body as string
        const hash = createHmac('sha256', secretKey)
            .update(stringRequest)
            .digest('base64')
        // verified request
        if (token === hash){
            return next();
        }
        // unverified request
        return res.status(401).send("Invalid Token");
    } catch (err) {
        return res.status(400).send("Bad Request");
    }
};
  
module.exports = verifyToken;

# index.js
const express = require('express');
const auth = require('./auth');
const port = 3000;
const app = express();
app.use(express.json());
app.post('/notifications-webhook', auth, (req, res) => {
    try {
        // insert code that processes the webhook
        console.log('notification webhook: ', req.body);
    }
    catch (err) {
        res.send(err);
    }
    res.status(200).send('Thanks Kard!');
});
app.listen(port, () => {
    console.log(`Example app listening on port ${port}`);
});