Purchase Webhooks

Purchase webhooks allow you to receive real-time notifications when players purchase any of your cobranded products available on the Lunar Client store. These notifications can be used to give the player an extra in-server item, thank them publicly in server chat, or just for your records.

Configuring a Webhook

There is currently no automatic process to configure a new webhook endpoint. Please reach out to your contact on the Lunar Client team to configure a webhook.

Webhook Signatures

It's important to verify the webhooks you're receiving are actually from Lunar Client. All webhooks will be sent with an X-Signature header, whose value should be checked prior to accepting the webhook.

This value is generated by computing a SHA256 HMAC hash of the body of the webhook. The secret to verify with will be provided to you as part of the setup process.

const signatureSecret = process.env.LUNAR_CLIENT_WEBHOOK_SECRET;
const body = ...; // This must be the raw body of the webhook. Parsing as JSON and re-serializing can create differences in whitespace.
 
const expectedSignature = crypto
  .createHmac("sha256", signatureSecret)
  .update(body)
  .digest("hex");

Webhook Types

• store.purchase.completed - A purchase has been completed, and a player has received your partnered product.
• store.purchase.refunded - A previously-completed purchase has been refunded by Lunar Client, and any partnered products have been removed.
• store.purchase.disputed - A previously-completed purchase has been disputed by the purchaser, and any partnered products have been removed.

Webhook Format

{
  "id": "0a838fbe-b3be-4ebf-ba0c-1ee55caf5c68", // Unique ID assigned to this webhook invoke
  "date": "2024-07-04T16:54:16.515Z", // Date this webhook was created, in ISO format
  "type": "store.purchase.completed", // Type of this webhook. See Webhook Types section above.
  "subject": {
    "packages": [
      {
        "id": 5362597, // Internal ID of the package purchased. This should be a stable identifier.
        "name": "Purple Prison (Hearts)", // Name of the package purchased.
        "quantity": 1 // Quantity purchased
      },
      {
        "id": 5362600,
        "name": "Purple Prison Necklace",
        "quantity": 1
      }
    ],
    "customer": {
      "username": "macguy", // Minecraft username
      "uuid": "7471b8e8-27c2-4354-a7d2-bd6a82dc00a0" // Minecraft uuid, with dashes
    }
  }
}

Please note that webhooks will only be sent for purchases that are relevant to you. That is, you'll only receive webhooks for purchases of your partnered packages, and not other unrelated purchases.

Additionally, webhooks will be filtered to only include relevant packages. If a player makes a single purchase for one partnered package and one Lunar Client owned package, the webhook body will only contain details about the partnered package.