Webhook List

This page lists all webhook events Stash can send to your backend. Each event is triggered by a specific user action or system event. Use the table below to see what's available, then expand the tabs for full payload examples.

Available webhooks

PURCHASE_SUCCEEDED is the primary event for granting items; always subscribe to it. PURCHASE_REFUNDED should be handled to revoke or adjust granted items. The remaining events are optional and used mainly for analytics, marketing, and behavior tracking.

CATALOG_REJECTED, CATALOG_ITEMS_DROPPED, CATALOG_DATA_CONFLICT and CATALOG_TEXT_FALLBACK report problems in your Real-time Catalog that you can fix. To start receiving them, contact your Stash engineering partner.

LOGIN_FAILED is off by default, so an endpoint that rejects unknown event types is not affected. Once your endpoint accepts the event, contact your Stash engineering partner to turn it on for your shop.

Payload structure

All v1 webhooks follow a consistent base structure:

{
  "type": "PURCHASE_SUCCEEDED",
  "environment": "test",
  "shopId": "your-shop-uuid",
  "purchaseSucceeded": {
    // Event-specific payload
  }
}

type, environment and shopId are on every v1 event. The event's payload sits under a key named for the event, such as purchaseSucceeded for PURCHASE_SUCCEEDED; each example below shows its key.

• environment is "test" (test/staging) or "production" (live). Use it to distinguish test traffic from real transactions.
• shopId is the ID of the shop that sent the event. Use it to route events when one endpoint serves several shops.

Webshop session

checkoutSessionId identifies one player's browsing session in your webshop. Events from the same session carry the same value, from catalog views through checkout and the purchase. After 30 minutes without activity, the player's next action starts a new session with a new checkoutSessionId. A new browser tab can also start a new session. Treat it as an opaque string.

• Group a session's events: collect every event with the same checkoutSessionId.
• Join a purchase to its funnel: a PURCHASE_SUCCEEDED or PURCHASE_FAILED carries the checkoutSessionId of the views and clicks that led to it.
• Match the purchase to your purchase calls: use transactionId (or orderId on a "Cart" purchase), as described under PURCHASE_SUCCEEDED. checkoutSessionId is not sent on RegisterPayment or ConfirmPayment.

On PURCHASE_REFUNDED, checkoutSessionId is the session of the original purchase, not of the refund.

These events can carry it: PURCHASE_SUCCEEDED, PURCHASE_FAILED, PURCHASE_REFUNDED, FREE_ITEM_REDEEMED, LOGGED_IN, VIEW_ITEM, VIEW_CATALOG_SECTION, VIEW_CHECKOUT_PAGE, VIEW_PRODUCT_DETAIL_PAGE, CART_BUTTON_CLICK, BUY_NOW_ITEM_CLICK and PAY_BUTTON_CLICK. It is omitted when the event is not tied to a webshop session, for example a purchase through a Stash Pay checkout link your backend created. It may also be omitted when analyticsConsent is "DECLINED" or "UNANSWERED". OPEN_PAYMENT, MUTATE_CART, LOYALTY_MILESTONE_CLAIMED, LOGIN_FAILED, OFFER_SLOT_MISMATCH and the CATALOG_* events never carry it.

Analytics consent

analyticsConsent is the player's answer to your webshop's analytics consent banner. VIEW_ITEM, VIEW_CATALOG_SECTION and BUY_NOW_ITEM_CLICK carry it.

Depending on your webshop, userId and checkoutSessionId are either sent with every answer, or omitted unless the answer is "ACCEPTED". A view or click without a userId can also come from a signed-out visitor. To find out which applies to your shop, contact your Stash engineering partner.

The field is omitted when no answer was reported, for example when your webshop shows no consent banner. It describes the banner answer only: it is not a permission that Stash grants, and it does not authenticate the event.

Detailed payload examples

Pick the event you're integrating to see its full JSON payload.

{
  "type": "PURCHASE_SUCCEEDED",
  "environment": "test",
  "shopId": "your-shop-uuid",
  "purchaseSucceeded": {
    "timeMillis": 1640995200000,
    "transactionId": "txn_789",
    "orderId": "order_abc123",
    "checkoutLinkId": "checkout_xyz789",
    "currency": "USD",
    "userId": "user_123",
    "items": [
      {
        "id": "item_456",
        "guid": "item_456_summer",
        "quantity": 2,
        "price": "9.99",
        "metadata": {
          "category": "weapons",
          "rarity": "legendary"
        },
        "purchasePackId": "summer-offer",
        "version": "5",
        "templateKey": "starter-offer-v2"
      }
    ],
    "tax": "1.50",
    "total": "21.48",
    "taxDetails": {
      "items": [
        {
          "label": "Sales Tax",
          "isInclusive": false,
          "amount": "1.50",
          "percentage": "7.5",
          "country": "US",
          "state": "CA"
        }
      ]
    },
    "emailMarketingOptIn": true,
    "regionCode": "US",
    "source": "StashPay",
    "ipAddress": "192.168.1.1",
    "paymentMethodType": "PAYMENT_METHOD_TYPE_CARD",
    "checkoutSessionId": "8f3c2b1e-6a4d-4c9e-9b2f-5d7a1e0c3b46"
  }
}

Common fields

Several fields appear across multiple webhook types. Only type, environment and shopId are on every v1 event; check the event's example above for the rest.

Subscription Events (v2)

Subscription events notify your system of subscription lifecycle changes. See the Subscriptions guide for full integration details.

Available subscription events

v2 Payload structure

Subscription webhooks use a different structure from v1 events:

{
  "type": "subscription.event_name",
  "data": {
    // Subscription object
  }
}

Detailed subscription payloads

{
  "type": "subscription.created",
  "data": {
    "id": "sub_xyz789",
    "external_account_id": "player_123",
    "plan_id": "plan_abc123",
    "status": "active",
    "period": {
      "value": 1,
      "unit": "month"
    },
    "trial_end": "2024-02-01T00:00:00Z",
    "access_end_date": "2024-03-01T00:00:00Z",
    "current_period_end": "2024-03-01T00:00:00Z",
    "next_billing_date": "2024-03-01T00:00:00Z",
    "cancel_at_period_end": false,
    "canceled_at": null,
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Subscription object fields

Payment Events (v2)

Payment webhooks notify your backend about individual payment outcomes. They use the same v2 payload format as subscription events (type + data). These events fire for subscription payments and other Stash Pay checkout flows.

Available payment events

Detailed payment payloads

{
  "type": "payment.succeeded",
  "data": {
    "id": "pay_abc123",
    "external_account_id": "player_123",
    "currency": "USD",
    "subscription_id": "sub_xyz789",
    "succeeded_at": "2024-01-01T00:00:00Z",
    "tax": "1.50",
    "total": "10.99",
    "metadata": {
      "custom-key": "customer-value"
    }
  }
}

Payment object fields