WireLinter is a local-first integration linter. It watches the real HTTP exchange between your app and a provider and tells you when the integration is wrong even when the request itself appears to have worked.
It catches things such as invalid signatures, changed raw bodies, missing headers, bad payloads, slow acknowledgements and semantic errors hidden inside HTTP 200 responses.
WireLinter stays next to your application while you debug. It is not a production webhook receiver, public tunnel or general API client.
Install the standalone binary on Linux or macOS:
curl -fsSL https://raw.githubusercontent.com/Raskinkamar/WireLinter/main/scripts/install.sh | shOn Windows PowerShell:
irm https://raw.githubusercontent.com/Raskinkamar/WireLinter/main/scripts/install.ps1 | iexThen just run:
wirelintWireLinter asks which integration you want to inspect and guides you from there. You do not need to know pack IDs, Trace JSON or the internal commands to get started.
You can also skip the prompts when you already know what you want:
# Incoming webhook
wirelint mercadopago http://localhost:8000/webhook
# WhatsApp webhook
wirelint whatsapp http://localhost:8000/webhook
# Outbound API
wirelint github-api https://api.github.comBrowse the bundled integrations with friendly names:
wirelint integrations
wirelint integrations --region BRWant to see the report format without configuring anything?
wirelint demoWireLinter does not collapse everything into success/failure:
pass enough evidence exists and the rule passed
fail enough evidence proves the rule was violated
open the rule applies, but the capture cannot prove the result
notApplicable the rule does not apply to this exchange
open is intentional: if a secret or another piece of evidence is missing, WireLinter says it cannot prove the result instead of guessing.
Point WireLinter at the webhook endpoint already running in your application:
export STRIPE_WEBHOOK_SECRET='whsec_...'
wirelint stripe http://127.0.0.1:3000/webhooks/stripeWireLinter listens locally on http://127.0.0.1:4545/, forwards the exact request body to your application and prints a report after every delivery.
Configure the provider, tunnel or local provider CLI to send the webhook to WireLinter instead of directly to your app. For Stripe CLI, for example:
stripe listen --forward-to http://127.0.0.1:4545/Trace persistence is off by default because webhook bodies can contain sensitive data. Advanced users can opt into it with --save-dir.
The explicit command remains available:
wirelint listen stripe http://127.0.0.1:3000/webhooks/stripeFor an outbound integration, give WireLinter the provider base URL:
wirelint github-api https://api.github.comWireLinter starts a local proxy on http://127.0.0.1:4546/. Point your application's provider base URL at that local address while debugging.
For GitHub GraphQL, for example, the app can call:
http://127.0.0.1:4546/graphql
WireLinter forwards the request to GitHub, returns the provider response to your app and evaluates the captured exchange. That lets it distinguish HTTP transport success from a GraphQL errors result inside the response body.
The explicit form remains available:
wirelint proxy github-graphql-api https://api.github.comCommon credential-bearing headers and query parameters are redacted in outbound evidence before optional persistence. Request and response bodies can still contain sensitive data.
Saved captures are useful for reproducing a problem or running WireLinter in CI, but they are not required for normal first use.
The short form is:
wirelint github ./examples/traces/github-valid.jsonThe explicit form remains available for scripts and CI:
wirelint lint --provider github ./examples/traces/github-valid.jsonAn integration ID describes a concrete protocol surface, not an entire company. Different authentication modes, traffic directions or setup phases remain separate when their behavior differs materially.
For example:
githubdescribes inbound GitHub webhook delivery whilegithub-graphql-apidescribes outbound GitHub GraphQL calls;meta-whatsapp-webhook-verification,meta-whatsapp-webhooksandmeta-whatsapp-cloud-apiseparate callback verification, signed delivery and outbound message calls;gitlab-webhooksandgitlab-webhooks-secret-tokenare different authentication contracts;vtex-order-hook-setup-pingandvtex-order-hook-deliverycover different phases of the same integration;docusign-connect-hmac-single-keyintentionally does not claim every DocuSign Connect key configuration.
Users normally do not need to type these full IDs. The CLI resolves human aliases when the choice is unambiguous and asks when it is not.
wirelint integrations
wirelint integrations --region BRRead Provider contracts for naming, secrets, validation and scope.
Every acquisition path produces the same canonical Trace internally. A provider pack evaluates that evidence with JSON Schema, CEL and a small set of trusted primitives for operations that should not expose secret material to pack code.
saved capture / inbound listener / outbound proxy
|
v
Trace
|
v
provider pack
/ | \
schema CEL trusted primitives
|
v
Report
Those are implementation concepts, not prerequisites for using the CLI. Provider-specific policy belongs in packs/; the Go core implements reusable mechanisms rather than vendor-specific branches.
Current Pack Protocol generations are:
- 1.0 — JSON Schema and CEL rules;
- 1.1 — declarative signature recipes;
- 1.2 — evidence-aware
requiressemantics; - 1.3 — trusted exact secret matching;
- 1.4 — trusted SHA-256 digest matching for keyed preimage contracts.
See Core concepts and Architecture decisions.
The stable explicit commands remain available for automation and advanced workflows:
wirelint lint
wirelint listen
wirelint proxy
wirelint providers
wirelint validate-pack
wirelint demo
wirelint version
Run wirelint help or read the CLI reference for flags and advanced options.
- Getting started
- Core concepts
- CLI reference
- Result semantics
- Provider contracts
- Debugging live webhooks
- Debugging outbound APIs
- Writing provider packs
- Development guide
- Security model
The documentation index is at docs/README.md.
cmd/ executable entrypoints
internal/ engine, pack loader, live acquisition and trusted runtime
packs/ bundled provider contracts
schemas/ public JSON schemas used by the protocol
examples/ canonical traces used in examples and tests
scripts/ build and release tooling
docs/ user guides, reference material and ADRs
See Development before changing the core.
Provider changes must be backed by primary provider documentation or an official SDK. A core change should solve a provider-neutral mechanism rather than a single vendor case.
Start with CONTRIBUTING.md.
MIT