Webhook

Our webhook allows you to be automatically notified of events such as: voucher state change / change in our offer catalog.

If you need to programmatically confirm previously reserved vouchers, this webhook is mandatory.

Notification URL

To subscribe to notifications, you must fill out your endpoint in the back-office, tab Informations > Configuration Plateforme, field URL de notification (https).

Your endpoint should return a HTTP 200 status code to acknowledge the notification was received. Otherwise, our backend will repeatedly retry to call you (exponential backoff) during a 5-minute time window. During development phase, you can use services such as ngrok (https://ngrok.com/) ou https://webhook.site/ to redirect webhook on you local machine.

Here is a screenshot of the back-office:

Events

Offer catalog update notifications

store/enabled

This event is raised as soon as a store appears in the Jackpot catalog (either a new store or a previously out-of-stock store). The store properties are returned into the data field.

{
  "event": "store/enabled",
  "id": "b8338d8f-f713-453e-af4a-f843826f2b1d",
  "createdAt": "2022-02-03T14:44:10.741Z",
  "message": {
    "storeId": "c2a4af8b-b77f-4af2-b831-4cbe9789b52a",
    "data": {
      // All store properties
    }
  }
}

The store properties returned into the data field are identical to the ones returned by route v2/stores. Please read the documentation of /v2/stores https://api.jackpot-io.com/documentation to know the full and actualized list of a store's properties.

Find below an example with the store properties returned by the /v2/stores route on 2022 Feb 1st:

{
  "event": "store/enabled",
  "id": "b8338d8f-f713-453e-af4a-f843826f2b1d",
  "createdAt": "2022-02-03T14:44:10.741Z",
  "message": {
    "storeId": "c2a4af8b-b77f-4af2-b831-4cbe9789b52a",
    "data": {
      "id": "c2a4af8b-b77f-4af2-b831-4cbe9789b52a",
      "name": "Nom de l'enseigne",
      "slug": "slug-enseigne",
      "baseColor": "#654cb2",
      "storeLogoSmall": "https://site.com/image.png",
      "storeLogoMedium": "https://site.com/image.png",
      "storeLogoLarge": "https://site.com/image.png",
      "voucherWithContinuousValue": false,
      "mentions": "<p>Mentions de l'offre au format HTML</p>\n",
      "storeImage315": "https://site.com/image.png",
      "storeImage1080": "https://site.com/image.png",
      "shippingTime": "0",
      "shippingInfos": "Envoi immédiat",
      "categories": [Food],
      "description": "<p>Description de l'offre au format HTML</p>\n",
      "validityDate": "2023-02-03T14:44:10.695Z",
      "backgroundImage670": "https://site.com/image.png",
      "backgroundImage1080": "https://site.com/image.png",
      "voucherValueMin": 20,
      "voucherValueMax": 50,
      "voucherPossibleDiscreteValues": [20,30,50],
      "discounts": [
        {
          "voucherValueMin": 20,
          "voucherValueMax": 800,
          "discountRate": 10
        }
      ]
    }
  }
}

On the staging environment, you can manually trigger a store/enabled event from the back-office (https://admin.test.jackpot.cm): menu “Ma plateforme”, tab "Informations > Webhook". Select a store then click button “Envoyer un webhook de test”.

store/disabled

This event is raised when a store is removed from the Jackpot catalog (either definitively or temporarily, typically because out of stock). You should then stop offering this store to your users (via its ID returned in the storeId property).

{
  "event": "store/disabled",
  "id": "ce125ecf-759d-4ba6-b174-afb4d1c5e812",
  "createdAt": "2022-02-03T14:44:04.065Z",
  "message": {
    "storeId": "c2a4af8b-b77f-4af2-b831-4cbe9789b52a"
  }
}

On the staging environment, you can manually trigger a store/disabled event from the back-office (https://admin.test.jackpot.cm): menu “Ma plateforme”, tab "Informations > Webhook". Select a store then click button “Envoyer un webhook de test”.

store/update

This event is raised when some of a store's properties are modified, for instance:

its conditions: “shippingTime”, “validityDate, “mentions” etc.,
its values: “voucherValueMin", "voucherValueMax, “voucherPossibleDiscreteValues” etc.
its discount rates: "discounts"
its visual elements: "logos", "images", "baseColor"

In the following example, the store name is changed, and the value "100€" is added to the list (after 20 / 30 / 50). You can get the full list of the store properties via data and you can get the updated properties via updatedAttributes:

{
  "event": "store/update",
  "id": "be473201-7b6b-4702-80fd-37028d55976f",
  "createdAt": "2022-02-03T15:05:55.239Z",
  "message": {
    "storeId": "c2a4af8b-b77f-4af2-b831-4cbe9789b52a",
    "data": {
      // Liste exhaustive des propriétés de l'enseigne, parmi lesquelles :
      "name": "Enseigne new",
      "voucherValueMax": 100,
      "voucherPossibleDiscreteValues": [20,30,50,100],
    },
    "updatedAttributes": {
      "name": {
        "previousValue": "Nom de l'enseigne",
        "newValue": "Enseigne new"
      },
      "voucherValueMax": {
        "previousValue": 50,
        "newValue": 100
      },
      "voucherPossibleDiscreteValues": {
        "previousValue": [20,30,50],
        "newValue": [20,30,50,100]
      }
    }
  }
}

You'll find an example on this properties in the "store/enabled" section above.

A field might also be added/removed.

For instance, for a store whose configuration is changed from discrete values (20/30/50€) to continuous values (from 20 to 50€):

Property voucherWithContinuousValue is changed from "false" to "true"
Property voucherPossibleDiscreteValues is now useless and thus disappears

{
  "event": "store/update",
  "id": "438591f5-4171-4aca-a5f1-a813eed316c9",
  "createdAt": "2022-02-03T15:15:31.375Z",
  "message": {
    "storeId": "c2a4af8b-b77f-4af2-b831-4cbe9789b52a",
    "data": {
      // Full list of the store's properties, among which:
      "voucherWithContinuousValue": true,
      // voucherPossibleDiscreteValues is gone
    },
    "removedAttributes": [
      "voucherPossibleDiscreteValues"
    ],
    "updatedAttributes": {
      "voucherWithContinuousValue": {
        "previousValue": false,
        "newValue": true
      }
    }
  }
}

Symmetrically, for a store changed from continuous values to discrete values (20€, 30€ et 50€):

Property voucherWithContinuousValue is changed from "true" to "false"
Property voucherPossibleDiscreteValues is added

{
  "event": "store/update",
  "id": "02115e72-ad10-4e6a-aa0d-cf857b5c37d1",
  "createdAt": "2022-02-03T15:15:22.472Z",
  "message": {
    "storeId": "c2a4af8b-b77f-4af2-b831-4cbe9789b52a",
    "data": {
      // Full list of the store's properties, among which :
      "voucherWithContinuousValue": false,
      "voucherPossibleDiscreteValues": [20,30,50],
    },
    "addedAttributes": [
      "voucherPossibleDiscreteValues"
    ],
    "updatedAttributes": {
      "voucherWithContinuousValue": {
        "previousValue": true,
        "newValue": false
      }
    }
  }
}

Bottom line:

data contains all the store's properties, following a change
updatedAttributes only contains the changed properties, if any (only present if non empty)
addedAttributes only contains the added properties, if any (only present if non empty)
removedAttributes only contains the removed properties, if any (only present if non empty)

On the staging environment, you can manually trigger a store/update event from the back-office (https://admin.test.jackpot.cm): menu “Ma plateforme”, tab "Informations > Webhook". Select a store then click button “Envoyer un webhook de test”.

Voucher update notifications

These events are raised whenever a voucher state change occurs:

coupon/reserved
coupon/canceled
coupon/confirmed
coupon/ready
coupon/refunded
coupon/refund_rejected

You should base your application logic on those events:

If you are in "manual confirmation" mode, you can programmatically confirm a reserved voucher ( via route /v2/vouchers/{voucherId}/confirm) upon reception of the coupon/reserved event.
You can send the voucher to your user as soon as you get the coupon/ready notification. Note that a signed URL (valid for one hour) to the voucher PDF is provided in the signedUrl property (if expired a new one can be requested via route “GET /v2/vouchers/{voucherId}/signedurl”)

If you fill the notificationKey property when generating your session JWT, this notification key will be present in the payload sent with every voucher notification. This can help to find a voucher reservation in case you missed the return of the /v2/stores/{storeId}/reserve-voucher-by-price or /v2/stores/{storeId}/reserve-voucher-by-value route for some reason.

{
  "event": "coupon/ready",
  "id": "09a5cdfc-03db-444e-84e9-1dbd29c34377",
  "createdAt": "2021-07-01T15:05:20.360Z",
  "message": {
    "id": "643ee25e-b705-42e0-b074-28265ba0adc8",
    "state": "READY",
    "value": "80.00",
    "initialAmount": "68.80",
    "reservationDate": "2021-07-01T15:05:15.311Z",
    "validityDate": "2022-03-28",
    "resaExpireDate": "2021-07-16T15:05:15.311Z",
    "couponId": "XSLCNKVBCJ",
    "confirmDate": "2021-07-01T15:05:15.431Z",
    "sendDate": "2021-07-01T15:05:17.265Z",
    "canceledDate": null,
    "storeName": "Morphée",
    "price": "68.80",
    "email": "sam@jackpot-io.com",
    "notificationKey": "VOTRE_REF_INTERNE",
    "signedUrl": "https://storage.googleapis.com/vouchers-jackpot-staging/643ee25e-b705-42e0-b074-28265ba0adc8.pdf?GoogleAccessId=gcp-storage-staging%40polar-access-225113.iam.gserviceaccount.com&Expires=1625155520&Signature=YxWB55ZfWorrOAvEDV421Hp7%2FtGCQrbfQ2wrDeX%2FgwOsl%2BuX2p53Lb6WrxUswZLaHjZzENMQZHkjrQLq%2FjQ2lBiiXQFhV4t7yX%2BU3cJTNO3FD81q42bfMHUBQUTOlm6rk36uZYKS3KH0zoSSGAcj3IHYjoeCwm7Bv1phORuWbK%2BRkS6bx2wBRS0Ijm0UIWxT%2FfMeNCBNv9w9JCcE%2BRUW7m52hr64PAskifGMdpCgGpeBVThO0hrkdxaJy65FH7Jfrj8kVGUPEGWmsl%2FK6EjnfbWwQiOm9onZSfXBsJ7%2FsCj3AsZ6YoJBe0IiwJC%2BXMcsMeSUTkQX1DK7mX2ERuJqkw%3D%3D"
  }
}