Getting Started

The Reward Postback is a webhook that Playfull uses to notify developers when a user receives an in-game reward.

Playfull sends a POST request to your configured webhook URL. The request body is JSON and is signed using your client secret; the signature is provided in the x-playfull-signature request header.

Verifying postback signature

const crypto = require('crypto')
 
app.post('/webhook', async (request, response) => {
  const signature = request.headers['x-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: number (quantity of the item)
  timestamp: long (UNIX seconds),
  metadata: json
}

When integrating, configure your webhook URL and the item_id in the developer portal as required. Only a single top-level item_id is supported per request. To include multiple rewarded items, place them inside the metadata object (for example, an items array). Below is an example payload that contains multiple items:

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

Batch Sending Limits