Stash Webhooks

Webhooks are automated notifications that Stash sends to your backend when certain events occur in Stash products. They are a core component of integrating Stash Pay and Stash Webshop. When an event is triggered—such as a player making a purchase—Stash sends an HTTP POST request (with a JSON payload) to the webhook URL you've configured in Stash Studio.

Common webhook event examples include:

• Purchase completed successfully
• Items added or removed from cart
• User views a product
• Payment intent created
• Subscription created, renewed, or canceled

By handling these webhook notifications, your backend can:

• Grant items to players after successful purchases
• Track user behavior and analytics
• Maintain synchronization between your game and Stash
• Manage subscription access and renewals
• Process refunds and handle edge cases

The following diagram illustrates a typical webhook flow:

Webhook formats

Stash webhooks use two payload formats:

v1 format (existing)

Used by purchase and webshop events (PURCHASE_SUCCEEDED, MUTATE_CART, etc.). These use uppercase event types with camelCase nested objects:

{
  "type": "PURCHASE_SUCCEEDED",
  "purchaseSucceeded": { ... }
}

v2 format (new)

Used by subscription events (subscription.created, subscription.canceled, etc.). These use lowercase dot-notation event types with a data object:

{
  "type": "subscription.created",
  "data": { ... }
}

New webhook events will use the v2 format. Your webhook handler should support both formats. See the Webhook List for detailed payload examples.

Configure webhooks

To start receiving webhooks, you need to set them up in your Stash Studio project settings:

Here, you can add a new webhook by entering the URL of your webhook listener endpoint. Stash Studio will also provide you with a unique webhook secret, which you should use to verify the signature of each incoming webhook message.

Are webhooks required to launch?

Yes, webhooks are required for production launches when using Stash products that involve purchases or transactions. Webhooks are essential for:

• Granting items to players: When a purchase succeeds, you need the PURCHASE_SUCCEEDED webhook to grant items to the player's account
• Maintaining data consistency: Webhooks ensure your backend stays synchronized with Stash's transaction state
• Handling edge cases: Webhooks provide reliable delivery even if the client disconnects during a purchase

Key Requirements:

• Your endpoint must accept HTTPS (not HTTP) connections
• Your endpoint must return 200 OK to acknowledge receipt
• Your endpoint should respond within 30 seconds
• Your endpoint should be accessible from the internet

For development and testing, you can use webhook testing tools or temporarily disable webhook verification, but production deployments require a properly configured webhook endpoint.

If you're experiencing issues with webhook delivery, see our troubleshooting guide for common solutions.