Custom Webhook

Use the custom webhook when your store is not Tebex. Your backend posts signed events to ShardAnalytics, and the platform treats them like any other store integration: revenue, declines, refunds, player matching, and campaign attribution.

Endpoint

POST https://api.shardanalytics.com/v1/webhooks/<tenantId>/custom

The endpoint is deterministic. You do not call an API to create it; configure it in Organization Settings → Payments → Custom.

Signature

Every request must include an X-Signature header computed with HMAC-SHA256 over the raw request body:

bodyHash  = SHA256(rawBody)
signature = HMAC-SHA256(bodyHash, secret)

Send the lowercase hex digest in X-Signature. Compute it against the exact bytes you send, before any re-serialisation. The secret is set in the dashboard and stored encrypted.

Payload

{
  "type": "payment.completed",
  "transaction_id": "order-10231",
  "timestamp": "2026-10-04T18:22:11Z",
  "amount": 14.99,
  "currency": "USD",
  "player": {
    "id": "00000000-0000-0000-0000-000000000000",
    "username": "Steve_"
  },
  "packages": [{ "id": "vip-plus", "name": "VIP+ Rank Upgrade", "quantity": 1 }],
  "country": "GB",
  "creator_code": "stevebuilds"
}

Field	Required	Notes
type	Yes	payment.completed, payment.declined, or payment.refunded.
transaction_id	Yes	Unique identity for the event. Use your own order or event ID.
timestamp	No	ISO-8601 event time.
amount	No	Numeric amount in the store currency.
currency	No	Three-letter code; defaults to USD when omitted.
player.id / player.username	No	Used to match the purchase to a player.
packages[]	No	Item identifiers and names for package reporting.
country	No	Buyer country.
creator_code	No	Creator code for campaign attribution.

Validation event

When you set up the integration, ShardAnalytics may send a validation payload. Reply with the echoed ID:

// request
{ "type": "validation.webhook", "transaction_id": "test-validation" }

// response
{ "id": "test-validation" }

Delivery semantics

• Retries can deliver the same event more than once. Make your sender and the platform tolerant of duplicates by keeping transaction_id stable per event.
• Events may arrive out of order. Use timestamp for event time and transaction_id for identity.
• Replay protection is limited to signature verification; there is no documented timestamp tolerance window, so keep your signing secret private and rotate it if exposed.

Setup checklist

1. Choose Custom in Organization Settings → Payments.
2. Generate and store a secret in your backend.
3. Set the same secret in the dashboard.
4. Send a validation event and confirm the integration becomes active.
5. Map your store to servers if you want per-server revenue.