Skip to content
Skills Library
Programming · Building & coding

webhooks-impl

/webhooks-impl

Implements and validates the backend that receives Xsolla webhooks for a headless web shop — server-to-server notifications for user_validation, payment / order_paid, refund / order_canceled, and subscription events. Covers SHA-1 signature verification, idempotency, retry/response handling, IP allowlisting, payload shapes per delivery mode, and the common mistakes that break go-live. Use when building, modifying, debugging, or reviewing a webhook handler — including "implement Xsolla webhooks", "verify webhook signature", "handle payment / order_paid / refund webhooks", "grant items after purc

Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
11
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Implements and validates the backend that receives Xsolla webhooks for a headless web shop — server-to-server notifications for user_validation, payment / order_paid, refund / order_canceled, and subscription events. Covers SHA-1 signature verification, idempotency, retry/response handling, IP allowlisting, payload shapes per delivery mode, and the common mistakes that break go-live. Use when building, modifying, debugging, or reviewing a webhook handler — including "implement Xsolla webhooks", "verify webhook signature", "handle payment / order_paid / refund webhooks", "grant items after purc

Triggers from the description

implement Xsolla webhooksverify webhook signaturehandle payment / order_paid / refund webhooks
Original author description

Implements and validates the backend that receives Xsolla webhooks for a headless web shop — server-to-server notifications for user_validation, payment / order_paid, refund / order_canceled, and subscription events. Covers SHA-1 signature verification, idempotency, retry/response handling, IP allowlisting, payload shapes per delivery mode, and the common mistakes that break go-live. Use when building, modifying, debugging, or reviewing a webhook handler — including "implement Xsolla webhooks", "verify webhook signature", "handle payment / order_paid / refund webhooks", "grant items after purc

How it works

  1. Status
  2. When to use
  3. Prerequisites
  4. Steps
  5. Common pitfalls
  6. Agent test
Original SKILL.md headings · 142 lines, 944 words
SKILL.md preview
---
name: webhooks-impl
description: >-
  Implements and validates the backend that receives Xsolla webhooks for a
  headless web shop — server-to-server notifications for user_validation,
  payment / order_paid, refund / order_canceled, and subscription events.
  Covers SHA-1 signature verification, idempotency, retry/response handling,
  IP allowlisting, payload shapes per delivery mode, and the common mistakes
  that break go-live. Use when building, modifying, debugging, or reviewing a
  webhook handler — including "implement Xsolla webhooks", "verify webhook
  signature", "handle payment / order_paid / refund webhooks", "grant items
  after purchase", "webhook returns INVALID_SIGNATURE", "webhook idempotency /
  retries", or "headless webshop backend".
metadata:
  owner: e.chernykh
  domain: webhooks
  status: draft
---

## Status

This skill is a **draft** authored by the webhooks SME (@e.chernykh).

Detailed material lives in `references/`:
- [`references/events-and-payloads.md`](references/events-and-payloads.md) — delivery modes, event types, payload JSON, refund codes
- [`references/signature-verification.md`](references/signature-verification.md) — SHA-1 algorithm + Node/PHP examples
- [`references/handler-and-reliability.md`](references/handler-and-reliability.md) — responses, idempotency, retries, IP allowlist, **fulfillment (ask how goods are granted)**, full handler
- [`references/testing.md`](references/testing.md) — fixture replay vs live tunnel; when `payment` vs `order_paid` arrives
- [`fixtures/`](fixtures/) — sample `user_validation` / `order_paid` / `payment` bodies (+ `.raw.txt`)

## When to use

Use this skill when the developer wants to **receive and process Xsolla
webhooks on their own backend** for a headless web shop (their storefront on the
Xsolla catalog + Pay Station, without Site Builder). Trigger conditions:

- Implementing a webhook endpoint that grants items / currency after purchase
- Verifying the webhook signature or debugging `INVALID_SIGNATURE`
- Handling `user_validation`, `payment` / `order_paid`, `refund` /
  `order_canceled`, or subscription events
- Making webhook processing idempotent or handling retries correctly
- Reviewing an existing webhook handler before go-live

This skill covers **handler implementation** and how to test it. Enabling
webhooks + creating the secret in Publisher Account is a **manual** step in
**Prerequisites** below (not done by `merchant-setup`). Setting the live URL is
covered in `references/testing.md`.

## Prerequisites

```bash
export XSOLLA_WEBHOOK_SECRET=<project webhook secret key>  # server-side only, never client-side
export XSOLLA_ENV=sandbox                                  # default; "production" for prod
```

### Publisher Account — enable webhooks + secret (human)

The agent cannot create the secret in PA. **Ask the developer** to:

1. Open project webhooks (ids from `.env` per `merchant-setup`):

   ```text
   https://publisher.xsolla.com/{XSOLLA_MERCHANT_ID}/projects/{XSOLLA_PROJECT_ID}/edit/webhooks
   ```

2. **Create / generate the webhook secret key** (project secret used to sign
   notifications).
3. **Enable webhooks** for the project (Store / required notifications as shown in PA).
4. Put the secret in the backend `.env` (never the browser / never commit real values):

   ```bash
   XSOLLA_WEBHOOK_SECRET=<the key from PA>
   ```

5. Later set the **listener URL** (HTTPS) — local tunnel or deployed host — under the
   same webhooks settings (store path often
   `.../edit/webhooks/store`). See `references/testing.md`.

Without the secret in `.env`, signature verification always fails. Without
webhooks enabled + a reachable HTTPS URL, Xsolla never delivers live events
(fixtures still work for local replay).

Also needed:

- A backend that can read the **raw request body** (needed for signature
  verification) and a datastore for idempotency keys.
- Webhook URL must be **HTTPS** when Xsolla calls it — HTTP is rejected.

## Steps

1. **Know your delivery mode.** Projects registered after 2025-01-22 get
   **combined** webhooks (`order_paid` / `order_canceled` carry items + payment);
   older projects get **separate** (`payment` + `refund` plus `order_paid` /
   `order_canceled`). The JSON differs per mode — see
   `references/events-and-payloads.md`.

2. **Capture the raw body and verify the signature first.** The `authorization`
   header is `Signature <40-hex>`; recompute `lowercase(sha1(rawBody + secret))`
   and compare in constant time. Reject mismatches with `400 INVALID_SIGNATURE`.
   Full Node/PHP examples: `references/signature-verification.md`.

3. **Route by `notification_type` and fulfill:**
   - `user_validation` → confirm the user exists; `204` if yes, `400 INVALID_USER` if no.
   - `order_paid` → **grant** purchased goods (idempotently). `order_canceled` → revoke
     per the developer’s policy.
   - In separate mode, `payment` / `refund` also arrive — treat them as financial
     records only; do fulfillment on `order_*` to avoid double-granting.
   - Merchant-only tokens may send `payment` without a Store order — then fulfill
     on `payment` if that is the only success signal (see `testing.md`).
   - Subscription events (optional) → start / extend / revoke.
   **Ask the developer how users receive goods** in their product (inventory API,
   wallet, game server, …) and wire the handler to that path — do not invent a
   parallel grant system. Details:
   `references/handler-and-reliability.md` (Fulfillment).

4. **Make fulfillment idempotent.** Dedupe by transaction id
   (`billing.transaction.id` combined, `transaction.id` separate) using a unique
   constraint; on a duplicate, return the prior `2xx` without re-granting.

5. **Respond correctly and keep it fast.** `200/201/204` = success, `400` (+ error
   code) = permanent reject, `5xx` = transient (Xsolla retries). Target < 3s; do
   heavy work async. Webhooks are delivered **sequentially** — a failing handler
   blocks the rest of the flow.

6. **Harden and test.** Allowlist Xsolla's source IPs (still verify the signature).
   Prefer **fixture replay** for signature / routing / idempotency; use a **public
   tunnel** + sandbox purchase (developer sets the URL in PA) for live delivery.
   See `references/testing.md`.

## Common pitfalls

- **Re-serializing the body before hashing** — always sign the raw bytes. The #1
  cause of `INVALID_SIGNATURE`.
- **Returning `200` on a bad signature** — breaks Xsolla's setup test and hides
  attacks. Return `400 INVALID_SIGNATURE`.
- **Non-idempotent fulfillment** — granting items twice on a retried/duplicate
  webhook, or fulfilling on both `payment` and `order_paid` in separate mode.
  Dedupe by transaction id and fulfill only on `order_*`.
- **Misusing `5xx`** — it triggers up to 48h of retries for errors that will
  never succeed. Use `400` for permanent problems, `5xx` only for transient ones.
- **Ignoring or slowing `user_validation`** — a failing/slow validation handler
  blocks every downstream payment webhook; the user sees an error.
- **Granting without asking how** — inventing a demo inventory while the game
  already has a real entitlement path. Always ask how the buyer receives goods
  and map the webhook user id to that system.

## Agent test

Prompt: "Implement an Xsolla webhook handler for my headless shop that grants
items after purchase. Use Node.js/Express."

Result: the agent discovered and applied this skill (read `SKILL.md` + references,
including `testing.md` / fixtures), asked how goods are granted in the product,
scaffolded a raw-body Express endpoint, and smoke-tested with fixture POSTs:
`lowercase(sha1(rawBody + secret))` rejecting tampered bodies with
`400 INVALID_SIGNATURE`; `user_validation` returning `204`/`400 INVALID_USER`;
idempotent `order_paid` granting (replay returned `2xx` with no re-grant); no
double-grant in separate mode (`payment` recorded only); `5xx` reserved for
transient errors. ✅
Files in this package (11)
  • SKILL.md 8 KB
  • fixtures/order_paid.json 2 KB
  • fixtures/order_paid.raw.txt 1 KB
  • fixtures/payment.json 2 KB
  • fixtures/payment.raw.txt 1 KB
  • fixtures/user_validation.json 1 KB
  • fixtures/user_validation.raw.txt 1 KB
  • references/events-and-payloads.md 6 KB
  • references/handler-and-reliability.md 7 KB
  • references/signature-verification.md 2 KB
  • references/testing.md 5 KB

Versions

The database has no other skills named webhooks-impl.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version b6bc8b146920 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100dwolla-webhooks
    Receive and verify Dwolla webhooks. Use when setting up Dwolla webhook handlers, debugging X-Request-Signature-SHA-256 verification, or handling ACH payment events like customer_created, customer_transfer_completed, and customer_funding_source_verified.
  • 100logto-webhooks
    Receive and verify Logto webhooks. Use when setting up a Logto webhook endpoint, validating the logto-signature-sha-256 HMAC header, or handling events like PostSignIn, PostRegister, User.Created, User.Data.Updated and Grant.LimitExceeded.
  • 100webhook-integration
    Dodo Payments webhook handling, covering endpoint setup, Standard Webhooks signature verification on the raw body, payment, subscription, and refund event types, idempotency with webhook-id, retries, and local testing. Use when receiving Dodo events, verifying webhook-signature…
  • 90backend-webhooks
    Use this skill when the user says 'webhook', 'webhook receiver', 'webhook delivery', 'signature verification', 'HMAC', 'event delivery', 'outgoing webhook', 'incoming webhook', 'retry webhook', 'webhook endpoint'. This skill implements receiving, verifying, retrying, and…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.