Getting Started

The Reward Postback is a webhook designed to enable Playfull to send postback to developers when our users rewarded with in-game reward.

Playfull will send a POST request to your webhook url. The request payload will be JSON formatted and will be signed using the client secret key. The resulting signature will be included in the request header Playfull-Signature.

Verifying postback signature

const crypto = require('crypto')
 
app.post('/webhook', async (request, response) => {
  const signature = request.headers['playfull-signature']
  const isValid = verifySignature(signature, request.body.toString())
})
 
const verifySignature = function (receivedSignature, payload) {
  const hash = crypto
  .createHmac('sha256', <secret_token>)
  .update(payload)
  .digest('base64')
  return receivedSignature === hash
}

Payload Definition

{
  id: string (unique id of the webhook request)
  user_id: string (user id),
  item_id: string (item id of the reward),
  quantity: string (quantity of the item)
  timestamp: long (UNIX seconds),
  metadata: json
}

When integrating the webhook, you will need to let us know the following so that it can be configured on our system:

item_id (required)
metadata (optional) for storing any additional information

Multiple items are supported in 1 request. In this case, item_id can be any placeholder value, and metadata will contain a list of items. Here's an example payload that contains multiple items:

{
  id: "[UUID]"
  user_id: "[USER_ID]",
  item_id: "MULTIPLE",
  quantity: "1"
  timestamp: 1749095869,
  metadata: {
    items: [
      {
        item_id: "some-item-1",
        quantity: "1"
      },
      {
        item_id: "some-item-2",
        quantity: "5"
      },
    ]
  }
}

Examples Limits