How to securely integrate a gamified coupon in another app via API & Webhooks?

This article will guide you on how to integrate a gamified coupon in your app and let each unique app user play only once.

Coupontools backend:

Build the coupon layout in the Coupontools dashboard
Find the campaign ID in the dashboard. It looks like this: cam_1234567890 (Contact support to enable this feature in your account)

App backend:

Use our Single Use API endpoint to create a unique URL for each app user:
https://docs.coupontools.com/api/coupon#create-single-use
You can find your API credentials in your Coupontools dashboard -> integrations -> rest API

The campaign ID is mandatory in the request. We advice you to store your unique app user ID in the"customid" field.
Optional you can add other data but that's not required.

### Note:
There is 1 parameter that is called: "duplicate_check"
If you pass the parameter "duplicate_check" -> "customid" our API will automatically manage a duplication check.
Our API will return the found session information if the "customid" is duplicated.
If you not pass the duplicate check parameter, our API will return a unique session for each API call.

Our API returns a unique URL for the requested customid.

{

	"status": {
		"status": "OK"
	},
	"campaign": "cam_12345",
	"action": "single_use_code_created",
	"single_use_code": "c43403t2fv7qz27in745p",
	"single_use_url": "https://digicpn.com/p/abc123/c43403t2fv7qz27in745p",
	"widget_validation_code": "c43403",
	"custom_validation_code": "102030405060708",
	"duplicate_found": true (only returned when checking for duplicates)
}

Store the "single_use_code" on your end with your userid
Grab the "single_use_url" and display that in your app for that user only.

Webhooks:

In your Coupontools dashboard -> integrations -> Webhooks you can set up your webhook URL for callbacks.



From the moment the user plays the game you'll receive a webhook:

{
  "id": "evt_5YoWeS6jKAXXhLUHnTIJ",
  "datetime": "2023-10-19 14:42:41",
  "livemode": "0",
  "type": "played_and_won",
  "coupon_code": "wwb551nf73e22vm7otdsa",
  "session": "wwb551nf73e22vm7otdsa",
  "campaign": "cam_1166764",
  "campaign_url": "https://digicpn.com/p/9gfjby",
  "session_url": "https://digicpn.com/p/9gfjby/wwb551nf73e22vm7otdsa",
  "coupon_url": "https://digicpn.com/p/9gfjby/wwb551nf73e22vm7otdsa",
  "coupon": {
    "coupon_code": "9gfjby",
    "friendly_name": "Campaign copy",
    "title": "Your coupon title here",
    "subtitle": "Your coupon subtitle",
    "tags": "",
    "coupon_value": "Your^prize^here^3",
    "money_spent": null,
    "custom_validation_code": "",
    "customid": "",
    "folder": "0",
    "expirydate": ""
},
}

There are 2 webhook types:
"type": "played_and_won",
"type": "played_and_lost",

The webhook data will contain the sessionid (= single use code) + your customid (if passed) and the prize (coupon_value)

If the coupon has a claim page after the game, and the user completes the claim page (eg entering some data) you'll receive another webhook:
"type": "coupon_claimed".
This webhook will return all the captured data from the claim page.

Additional security:
You are able to pull via API the webhook details so you are 100% sure the webhook data comes from our server and not from a hacker.
https://docs.coupontools.com/api/others#webhooks-verification

You can store the received data and prizes.
We advice to keep a record from each prize and sessionID so you can avoid giving away duplicate prizes.
With https://webhook.site/ you can easily debug and test the webhooks.

Thanks for reading!
If you need additional support contact our support team (support@coupontools.com)

Updated on: 20/10/2023