CLI workflow
Test Stripe Webhooks with a CLI
Forward test events to a local endpoint, trigger a known fixture, and verify signature handling and idempotency.
Prepare tools, authentication, and evidence first
Install the recommended tools, confirm minimum permissions, and keep compatibility separate from real execution records.
Copy or download this workflow Skill
The Skill includes input and output contracts, recommended tools, approval points, rollback, and evidence boundaries. Review it against the active environment before saving.
---
name: test-stripe-webhooks-workflow
description: "Forward test events to a local endpoint, trigger a known fixture, and verify signature handling and idempotency."
---
# Test Stripe webhooks
## Intended outcome
Prove a webhook handler accepts and processes test events without touching live customers or money.
## Evidence boundary
- Tool status distinguishes `docs-verified` material from independent execution; the two are not interchangeable.
- The current registry does not attribute a tool execution to a particular agent, so compatible agents cannot be called tested agents.
- Reconfirm the target account, environment, version, and official documentation before execution.
- Never auto-execute an R2, R3, or confirmation-marked step; obtain explicit approval immediately before it runs.
## Recommended tools, installation, and authentication
- **Stripe CLI** (evidence: `docs-verified`, docs checked: `2026-07-10`, no independently executed version recorded)
- Install: `brew install stripe/stripe-cli/stripe`
- Authentication: browser login, restricted API key
- Minimum permissions: Use a restricted test-mode key and verify account and livemode before every write.
## Input contract
- Local webhook URL
- Stripe test account
- event type
- expected application state
## Output contract
- Forwarding session
- test event ID
- handler logs
- delivery and state assertions
## Safe workflow
1. **Start test forwarding** — Authenticate to the intended test account and forward events to the local handler.
- Input: Test account and local endpoint
- Output: Webhook signing secret and forwarding session
- Risk: `read-only`
- Command: `stripe listen --forward-to localhost:3000/api/webhooks/stripe`
2. **Trigger a fixture** — Generate a documented test event, keeping the event type and account visible.
- Input: Chosen test event type
- Output: Test event and delivery attempt
- Risk: `remote-write`
- Command: `stripe trigger payment_intent.succeeded`
3. **Verify behavior** — Check status code, signature validation, idempotency, logs, and expected test data.
- Input: Delivery output and application logs
- Output: Pass/fail assertions with event ID
- Risk: `read-only`
## Ask before proceeding
- Using any live-mode credential or command
- Triggering events in a shared test account
- Creating, refunding, or canceling real payment objects
## Rollback
- Delete disposable test fixtures when appropriate
- Reset local test data with the project’s fixture workflow
- Never treat a compensating live payment as a test rollback
## Official sources
- [Stripe CLI documentation](https://docs.stripe.com/stripe-cli) — Official CLI guidance for test events, webhook forwarding, logs, and resources.
Outcome, inputs, and outputs
Define the result and evidence before the agent selects a command.
Test Stripe Webhooks with a CLI: safe workflow
Run each step inside its stated boundary and verify the output before continuing.
Approval points and rollback
Pause at the listed decision points and keep recovery instructions beside the action.
CLI, MCP, or API?
Choose the interface by execution location, identity, output contract, and permission boundary.
Recommended approach
Keep the default workflow entirely in Stripe test mode and verify the account before every trigger.
Official evidence and references
Use these primary or upstream sources to verify current command behavior before acting.