CI runs and monitoring
How it works
- Plan. Your CI job asks MockCard for a run. MockCard returns the events for each scenario: duplicates, late, abandoned 3DS, declines. They come already signed, with their timing.
- Deliver. The Action or SDK sends them to your app inside the CI job (your app is on
localhost, which MockCard can't reach), at the planned moments. The two copies of a duplicate go concurrently. - Assert. The SDK runs your checks against your own database: was the order fulfilled exactly once, was the stock released.
- Score. Results go back to MockCard. The run is scored, stored in your history with its commit and branch, and fails the build when it's below your threshold.
Why status codes aren't enough
A handler that processes a duplicate twice still answers 200 both times. Only an outcome check (“one order for one payment”) catches it. That's why the SDKs let you add assertions, and why we recommend them over the Action alone once your suite is set up.
1. Project and keys
- In the dashboard, create a project for your app and pick its gateway format (Stripe or Razorpay). Copy the probe secret; it's shown once (needed in step 5).
- Create a CI key and store it as a CI secret (
MOCKCARD_API_KEY). CI keys can run checks and runs, but can't change projects, keys or billing. - Store your gateway's test-mode webhook secret on the project (recommended). MockCard then signs every event exactly as Stripe (
Stripe-Signature) or Razorpay (X-Razorpay-Signature) would, so your unchanged signature check runs too. Give your app the same test secret in CI. It's encrypted and never shown again.
| Environment variable | Where | Value |
|---|---|---|
MOCKCARD_API_KEY | CI | Your CI key (mc_…) |
MOCKCARD_PROBE_SECRET | Production app | The project's probe secret (mcp_…) |
STRIPE_WEBHOOK_SECRET | App in CI | The test-mode secret stored on the project (whatever name your app already uses) |
2. GitHub Action
The quickest start. Start your app in the job, then run the action. It fails the job below min-score and writes every check to the job summary.
# .github/workflows/payments.yml
name: Payment webhooks
on: [push, pull_request]
jobs:
chaos:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: 20 }
- name: Start the app
run: npm ci && npm run build && (npm start &) && npx wait-on http://localhost:3000
env:
STRIPE_WEBHOOK_SECRET: ${{ secrets.STRIPE_TEST_WEBHOOK_SECRET }} # same test secret as the project
- uses: mockcard/chaos-action@v2
with:
api-key: ${{ secrets.MOCKCARD_API_KEY }} # a CI key
project-id: prj_3f9a1c2b7d4e5f60
target: http://localhost:3000/api/webhooks/stripe
min-score: 100| Input | Required | Default | Description |
|---|---|---|---|
api-key | yes | — | A CI key, from a secret |
project-id | yes | — | prj_… |
target | yes | — | Your webhook URL as the runner reaches it |
scenarios | no | success, insufficient_funds, 3ds_challenge, 3ds_abandoned, duplicate, latency, limbo | Comma-separated |
min-score | no | 100 | Fail below this score (0–100) |
time-scale | no | 0.2 | 0–1; shrinks the latency and 3DS waits |
Outputs: run-id, score, status (passed · failed · error). The action checks status codes only; add an SDK test (next step) for outcome assertions.
3. SDKs: assert what your app did
The SDKs run a chaos run from inside your test suite, so your assertions can query your own database. Each assertion is named under a scenario and runs once every event has been delivered, so it sees the final state. Return true to pass, or false or a message to fail.
import { MockCard, runChaos, assertRunPassed } from "mockcard";
test("payment webhooks survive chaos", async () => {
const run = await runChaos(new MockCard(), { // reads MOCKCARD_API_KEY
projectId: "prj_…",
target: "http://localhost:3000/api/webhooks/stripe",
assertions: {
duplicate: { "order fulfilled once": async () => (await countPaidOrders()) === 1 },
"3ds_abandoned": { "stock released": async () => (await reservedStock()) === 0 },
},
});
assertRunPassed(run); // throws with every failed check listed
}, 60_000);| Platform | Install | Probe guard |
|---|---|---|
| Node.js | npm i -D mockcard | verifyProbe(), probeAckResponse() |
| Next.js | npm i @mockcard/nextjs | withProbeGuard(handler) |
| PHP | composer require --dev mockcard/mockcard-php | Probe::isProbe() / verify |
| Laravel | composer require mockcard/laravel | route middleware mockcard.probe, php artisan mockcard:chaos |
| Symfony | composer require mockcard/symfony-bundle | ProbeGuardSubscriber (automatic) |
| Python | pip install mockcard | verify_probe(), pytest fixture |
| Go | go get github.com/arixevalabs/mockcard-go | mockcard.ProbeGuard(secret, handler) |
| Ruby | gem install mockcard | MockCard::Probe |
| Rails | gem install mockcard-rails | Rack middleware, installed by rails g mockcard:install |
| WooCommerce | Plugins → Add New → “MockCard Payment Health” | Guards the whole store; no code |
Choosing scenarios
The default set (success, insufficient_funds, 3ds_challenge, 3ds_abandoned, duplicate, latency, limbo) covers the failures that lose money. Add the decline scenarios (do_not_honor, expired_card, incorrect_cvv) and network_timeout if your handler treats them differently. What each one expects is listed in the API reference. Good assertions to start with:
duplicate: exactly one order or credit per payment id.3ds_abandoned: the order is cancelled and reserved stock is back.limbo: the order is not fulfilled (nothing confirmed it).latency: one order, even if your client retried while the webhook was late.insufficient_funds: no fulfilment, and the customer can pay again.
4. Staging: push runs
If staging has a public URL, MockCard can deliver the run itself, at real timings, with no code in your repo. Use it from a deploy hook, or schedule it with a staging monitor (step 6).
curl -X POST https://www.mockcard.io/api/v1/runs \
-H "Content-Type: application/json" \
-H "X-Api-Key: $MOCKCARD_API_KEY" \
-d '{ "project_id": "prj_…", "mode": "push",
"target_url": "https://staging.example.com/api/webhooks/stripe" }'
# 202 → { "run": { "id": "run_…", "status": "running" } }
curl -H "X-Api-Key: $MOCKCARD_API_KEY" https://www.mockcard.io/api/v1/runs/run_…
# → { "run": { "status": "failed", "score": 86, "results": { "checks": [ … ] } } }Push runs check status codes only. Assertions need your database, so they live in pull runs.
5. Production probe guard
Production monitors never send chaos to production. They send one signed probe (MockCard-Probe: 1 plus MockCard-Signature, made with your project's probe secret). Your handler verifies it, skips all processing, and answers 200 with MockCard-Probe-Ack: skipped. A forged probe header can only make your handler skip, never process. Every SDK in the table above ships the guard. Set MOCKCARD_PROBE_SECRET in production and wrap your webhook route:
import { withProbeGuard } from "@mockcard/nextjs";
// Verified MockCard probes get 200 + MockCard-Probe-Ack: skipped. Your code never sees them.
// Reads MOCKCARD_PROBE_SECRET.
export const POST = withProbeGuard(async (req) => {
// normal Stripe / Razorpay handling
});Not using an SDK? The check is about fifteen lines; see the TypeScript and Python versions. Put it before your gateway signature check: a probe is not signed with your gateway secret.
6. Monitors and alerts
| Staging monitor | Production monitor | |
|---|---|---|
| Sends | Full push run (your chosen scenarios) | One signed probe |
| Schedule | Hourly, every 6 hours or daily | Hourly, every 6 hours or daily |
| Starts when | Domain verified | Domain verified and one probe acknowledged |
| Plan limits | Pro 3, Agency 25 monitors in total | Same |
- Create the monitor in the dashboard (or
POST /api/v1/monitors) with its URL and environment. - Verify the domain with a TXT record on
_mockcard.<host>(valuemockcard-verify=<token>) or by serving the token at/.well-known/mockcard-verify.txt, then click Verify. This stops anyone from pointing MockCard at a site they don't own. - Production only: deploy the probe guard, then click Run now. When the probe comes back acknowledged, the schedule starts. A handler without the guard is never sent scheduled events.
- Alerts: email and, optionally, a Slack incoming webhook. You hear when a monitor starts failing and when it recovers, not on every run. A weekly digest shows that everything is still being checked.
Scheduled runs don't use your monthly calls. “Run now” uses one.
7. Agencies
- One project per client store, up to 25. Each has its own gateway format, secrets, runs and monitors.
- Team seats: invite up to 4 teammates (the owner takes the 5th seat). They sign in with their own email and work in the same account; billing and team changes stay with the owner.
- White-label client reports: set your brand name and link in the dashboard, then share a project's report link with the client. It shows the current result for each scenario and the monitors' status under your brand, needs no account, and expires after 90 days.
Agency Team seats and client reports are Agency features. Everything else on this page works on Pro too.
Troubleshooting
| Symptom | Likely cause and fix |
|---|---|
| Every delivery fails with 400 or 401 | Signature mismatch. The app in CI must use the same test secret that's stored on the project, and must verify the raw body (no JSON re-parsing first). Without a stored secret, events carry X-MockCard-Signature, which your Stripe library won't accept. |
| Every delivery fails with no status | The app isn't reachable at target yet. Wait for it to start (wait-on), and check the port and path. |
| Deliveries time out | Each delivery waits 10 s. Move slow work (emails, fulfilment) out of the webhook request into a queue: gateways time out too. |
| latency passes in CI but fails on staging | CI shrinks the wait (time_scale 0.2). Staging uses the real 9 s, which may hit your proxy timeout and trigger a retry. |
| Probe answered 2xx but failed | The response lacked MockCard-Probe-Ack: skipped, so the probe reached your normal handler. Check MOCKCARD_PROBE_SECRET matches the project, and that the guard runs before anything else. |
| Probes stopped passing after a rotation | Rotating the probe secret invalidates the old one. Deploy the new secret, then Run now. |
domain_not_verified | DNS changes can take a while to propagate. The well-known file is usually the faster option. |
pro_required | Runs, monitors and chaos scenarios need Pro or Agency. |