Analyse
IntegrationsTebex

Integrations

Tebex

How the Tebex webhook works, how purchases are attributed, and how to handle refunds.

The Tebex integration is the most important one on Analyse. It's how raw store sales become attributed, per-player, per-Campaign revenue.

This page is the deeper "how it works under the hood" version. For the step-by-step setup, see Connect your store.

How the integration works

  1. A player buys something on your Tebex store.
  2. Tebex sends a webhook event to a unique Analyse URL set up for that Server.
  3. Analyse verifies the webhook signature with the secret Tebex gave you when you created the webhook, parses the event, and looks up the player by their Minecraft username.
  4. The purchase is attached to the player, the Campaign they joined through, and any Creator code they used.
  5. All of this happens in a second or two.

What events Analyse listens for

Analyse processes four payment events for revenue updates. In the Tebex dashboard they appear under Webhook types with these names (not the internal API strings):

Name in TebexWhat Analyse does
Payment CompletedCreates the purchase. Adds revenue to Player, Campaign, Creator code, Server.
Payment DeclinedRecords the failed attempt but does not count revenue.
Payment RefundedMarks the existing purchase as refunded and subtracts revenue.
Payment ChargebackMarks the purchase as charged back and subtracts revenue.

Tebex also sends a validation webhook when you test the endpoint during setup; Analyse uses that to confirm the URL and secret.

Make sure those four payment types are ticked on your Tebex webhook. Leaving any off means Analyse will miss that kind of event.

Other webhook types Tebex may show

Your Tebex project can list additional types (for example Payment Dispute Opened, Payment Dispute Won, Payment Dispute Lost, Payment Dispute Closed, the recurring-payment events, and Basket Abandoned). You do not need to enable those for Analyse—today we only handle the four rows in the table above (plus validation for setup).

Payment Dispute Opened is separate from Payment Chargeback. For chargebacks to update revenue in Analyse, the Payment Chargeback type (when Tebex shows it) must be enabled alongside the other three payment rows.

How players get matched

Analyse matches purchases to a specific player using the Minecraft username on the purchase (case-insensitive). The Tebex customer object exposes that username; Tebex does not send the Minecraft UUID, so Analyse can't use UUIDs here.

If the username on the purchase has ever joined the Server, the purchase is attached to that player and inherits their original Campaign. If no matching player is found, the purchase is still recorded at the Server level but shows as "Unmatched" on the Revenue page.

This is usually fine. Unmatched rows tend to be test purchases, staff adjustments, or someone who bought something on the store before ever logging in.

Package filtering

By default Analyse tracks every purchase on your Tebex store. If you'd rather only attribute specific packages (e.g. just your real paid ranks, not internal admin adjustments or giveaways), connect your Tebex Public Token in Settings → Integrations → Tebex.

Once the token is saved, Analyse pulls your package list from Tebex and lets you tick exactly which packages to track. Anything unticked is silently ignored on incoming webhooks.

  • Token lives at Tebex → Integrations → API Keys → Public Token.
  • Without a token set, every package is tracked (the default).
  • You can change the selection any time.

The webhook endpoint

Each Server in Analyse has its own unique webhook URL. That's how multi-Server networks stay clean: each Tebex store (or category) points at the Server that should own the revenue.

One Tebex store per Server

If your Network runs multiple gamemodes on one Tebex store, you can still split revenue per Server using Tebex categories. Point each category's webhook at the right Server. We're happy to help in Discord if your setup is unusual.

Refunds and chargebacks

  • Payment Refunded subtracts from revenue immediately. The purchase stays visible in the table, marked as refunded.
  • Payment Chargeback is treated as an involuntary refund. The purchase is marked, revenue subtracted, and a small warning flag shows so you can spot abuse.
  • If you filter the Revenue page by "Refund = yes" you can review them all in one place.

Tax and VAT

Analyse stores the total paid amount as it arrives on the webhook. We don't split out VAT or region-specific taxes. If you need that breakdown for accounting, use Tebex's own reporting for tax and Analyse for attribution.

Testing the integration

Tebex has a "Send test event" button on every webhook endpoint. Press it and you should see:

  • A 200 response in the Tebex webhook log.
  • A green "Connected" badge in Analyse.

If you see 401 in Tebex's log, the webhook secret in Analyse doesn't match the one Tebex generated. Regenerate the secret in Tebex, paste the new one into Analyse, save.

Disabling or swapping

You can disable the integration at any time. Existing revenue stays visible, but new events stop being accepted. To swap between test and live stores, create a new Server in Analyse for test and point the test store there. Don't mix test and live data on the same Server.

Related