Webhooks

Webhook 

Webhooks Notify your application about events using webhooks.

Webhook Events

Our system currently supports the following webhook events:

Webhook event	Description
reward.earned	Triggered when a user gets a reward

Webhook Payload Schema

When an event occurs, a POST request will be sent to your specified URL with the following payload structure: For Coin type Reward

{
	"event": "reward.earned",
	"payload": {
		"rewards": [
			{
				"id": "fd9dd612-5387-42f7-aecb-d64e4ce657c0", //string;
				"reward_id": "845cdfaa-81a9-42e1-9755-c11df61823d4", //string;
				"reward_name": "10 Rs Off", //string;
				"nudge_id": "a4b43bf8-4972-44b3-a9bd-3370ebf14ed9", //string;
				"ext_id": "c4bb3bf8-45672-44b3-a9bd-3370ebf15rrgd", //string;
				"task_id": "bfrb3bf8-4972-44b3-78bd-3370ebf43ed9", //string;
				"quantity": 10, //number
				"coin": {
					//Object
					"value": 1 //number
				},
				"created_at": "2024-07-04T12:53:58.129Z" //string;
			}
		]
	}
}

Parameters

Name	Description
id	Unique id of the reward instance that the user won.
reward_id	Unique id of the actual reward created on Nudge dashboard.
reward_name	Name of the reward created on Nudge dashboard.
nudge_id	Unique id of the user generated by Nudge.
ext_id	Unique id of the user sent by you to Nudge.
task_id	Unique id of the campaign in which the user won the reward.
quantity	Quantity or units of the reward won by the user.
coin.value	Value of the coin type reward set up in the Nudge dashboard.
created_at	This represents the time when the instance of this reward is created.

For Coupon type rewards

{
	"event": "reward.earned",
	"payload": {
		"rewards": [
			{
				"id": "fd9dd612-5387-42f7-aecb-d64e4ce657c0", //string;
				"reward_id": "845cdfaa-81a9-42e1-9755-c11df61823d4", //string;
				"reward_name": "10 Rs Off", //string;
				"nudge_id": "a4b43bf8-4972-44b3-a9bd-3370ebf14ed9", //string;
				"ext_id": "c4bb3bf8-45672-44b3-a9bd-3370ebf15rrgd", //string;
				"task_id": "bfrb3bf8-4972-44b3-78bd-3370ebf43ed9", //string;
				"quantity": 10, //number
				"coupon": {
					"code": "ABCD", //string
					"discount": 20, //number
					"type": 1, // 1 (Flat Discount) | 2 (Percentage based discount) ,
					"expiry_at": null //string | null;
				},
				"created_at": "2024-07-04T12:53:58.129Z" //string;
			}
		]
	}
}

Parameters

Name	Description
id	Unique id of the reward instance that the user won.
reward_id	Unique id of the actual reward created on Nudge dashboard.
reward_name	Name of the reward created on Nudge dashboard.
nudge_id	Unique id of the user generated by Nudge.
ext_id	Unique id of the user sent by you to Nudge.
task_id	Unique id of the campaign in which the user won the reward.
quantity	Quantity or units of the reward won by the user.
coupon.code	The coupon code of the reward instance won by the user.
coupon.discount	Discount value of the coupon set up in the Nudge dashboard.
coupon.type	Type of the coupon setup in the Nudge dashboard. 1 for Flat discount and 2 for a percentage based discount
coupon.expiry_at	The expiry of the coupon instance won by the user
created_at	This represents the time when the instance of this reward is created.

Webhook Response Headers

Headers

Name	Description
x-idempotent-key	Unique identifier key for each event
x-nudge-signature	Signature of the request body

Setting up Webhooks

You can set up your webhooks using Nudge's dashboard.

• Add your endpoint.
• Add your secret that will be used to sign your requests.
• Select what data you want in your webhooks.

Verifying Webhook Signatures

Each request to your webhook URL will include a signature in the x-nudge-signature header which would be unique for each outgoing webhook (would be same for duplicate webhooks, which you could check through the x-idempotent-key header, see below). Follow these steps to verify the signature:

• Generate the Hash signature of the request body using your secret and HMAC with sha256.
• Compare the generated signature with the value in the x-nudge-signature header.

Node.js Code Snippet for Verification

const crypto = require('crypto');

const verifySignature = (bodyString, signature, secretKey) => {
	const hmac = crypto.createHmac('sha256', secretKey).update(bodyString).digest('hex');
	return hmac === signature;
};

// Example usage
const bodyString = JSON.stringify(request.body); // Convert the request body to a string
const signature = request.headers['x-nudge-signature']; // Get the signature from the header
const secretKey = 'boomBaam'; // Your secret key

if (verifySignature(bodyString, signature, secretKey)) {
	response.status(200).send('Signature verified');
} else {
	response.status(403).send('Invalid signature');
}

Idempotency

There could be scenarios where your endpoint might receive the same webhook event multiple times. This is an expected behaviour based on the webhook design. To handle duplicate webhook events:

• You can identify the duplicate webhooks using the x-idempotent-key header. The value for this header is unique per event.
• Check the value of x-idempotent-key in the webhook request header.
• Verify if an event with the same header is processed at your end.
  

Limits & considerations

• Max webhook timeout: 3,000 ms
• Retry Logic: Messages are retried up to 3 times
• Max payload size: 4 KB

  📘 Important

  If your API doesn't respond within 3 seconds, we will consider it as failed and retry

Request

Responses

200

Successful response

403

Invalid signature