Stash Webhooks
Learn about Stash webhooks - automated notifications sent to your backend when events occur across Stash products. Understand how to configure webhooks in Stash Studio and handle webhook events for player interactions, purchases, and more.
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
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
- Process refunds and handle edge cases
The following diagram illustrates a typical webhook flow:
Configure webhooks
Interactive Demo
To start receiving webhooks, you need to set them up in your Stash Studio project settings:
Open your project
Open your game project in Stash Studio.
Navigate to Settings
Go to the Settings section in the main navigation.
Configure Webhooks
Click on Webhooks.
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_SUCCEEDEDwebhook 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 OKto 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.
How is this guide?
Common Pitfalls
Learn about common mistakes when using API keys and how to avoid them. Understand environment confusion, key rotation impact, and security best practices.
Webhook Listener
Learn how to create a webhook listener on your backend to receive incoming Stash webhook requests, verify their authenticity using HMAC SHA-256 signatures, and respond appropriately to process events securely.