Guide
How to filter webhook events before they reach your app
Add conditions to the hook. Each condition has an if expression that reads the JSON body, or a request header as @headers.<name>, and a then block; then: { skip: true } stops the event there, so no destination is called. Hooksmith still verifies the sender and answers it with a 200, so the provider does not retry what you dropped. This guide filters a Stripe feed down to failed invoices above a threshold and disputes, then filters GitHub events by the X-GitHub-Event header, and shows how to test the rules before they go live.
Before you start
- The Hooksmith CLI, installed and logged in (curl -fsSL https://hooksmith.tech/install.sh | bash, then hooksmith login).
- A webhook source that sends JSON with the field you filter on. This guide uses Stripe's type.
- A destination URL for your app: a public HTTPS address.
Steps
Step 1: Create the hook from the Stripe preset
The preset keeps signature verification in place, so you filter only requests that are genuinely from Stripe.
terminalhooksmith init hooksmith new stripe-failures --preset stripe --yes
Step 2: Know the rules conditions follow
Conditions run top to bottom. The first one with skip: true that matches ends the run.
An if expression reads the JSON body by path, as in Stripe's type or GitHub's action. It reads request headers through @headers, such as @headers.x-github-event or @headers.x-shopify-topic. The header step below covers the rules for those.
Use ==, !=, <, <=, >, >=, &&, ||, ! and parentheses. Write literals in quotes: type == "charge.failed". An unquoted word is read as a path into the payload. Reach into objects with dots and arrays with an index, as in data.object.amount_due or entry[0].changes[0].value.statuses. A bare path such as cancelled_at is true when the field is present and is not empty, null, false or 0.
Number comparisons convert both sides to numbers. If the field is missing, the comparison is false.
Step 3: Write the filter
Replace the contents of .hooksmith/hooks/stripe-failures.yaml with the hook below. The first condition skips everything except failed invoices and new disputes. The second skips failed invoices under 1000 cents. The transform has no fields or body, so your app receives the original event JSON. The conditions read snapshot events (type without the v1. prefix and data.object), so keep Use thin events off on that Stripe destination.
Hooksmith has already verified the Stripe signature, so the request to your app does not carry a Stripe-Signature header. Put a shared secret in the destination URL you store, for example in the path or query, and check it in your app.
.hooksmith/hooks/stripe-failures.yamlapiVersion: hooksmith/v1 kind: Hook metadata: name: stripe-failures description: Stripe payment failures and disputes only spec: source: preset: stripe destinations: - name: primary url: ${DESTINATION_URL} method: POST timeout: 8s retries: max: 3 backoff: exponential initialDelay: 500ms transform: engine: handlebars conditions: - if: type != "invoice.payment_failed" && type != "charge.dispute.created" then: skip: true - if: type == "invoice.payment_failed" && data.object.amount_due < 1000 then: skip: true variables: - name: STRIPE_WEBHOOK_SECRET from: secret - name: DESTINATION_URL from: secretStep 4: Test an event that passes and one that is dropped
Save the two sample events. hooksmith test evaluates the conditions locally and prints either the body it would deliver or the condition that skipped it.
pass.json{ "id": "evt_1", "type": "invoice.payment_failed", "data": { "object": { "id": "in_1", "amount_due": 4900, "currency": "usd" } } }drop.json{ "id": "evt_2", "type": "charge.succeeded", "data": { "object": { "id": "ch_1" } } }terminalhooksmith test stripe-failures --payload ./drop.json hooksmith test stripe-failures --payload ./pass.json
output for drop.jsonpayload: ./drop.json skipped: true reason: type != "invoice.payment_failed" && type != "charge.dispute.created"
output for pass.jsonpayload: ./pass.json skipped: false destinations: primary body: { "id": "evt_1", "type": "invoice.payment_failed", "data": { "object": { "id": "in_1", "amount_due": 4900, "currency": "usd" } } }Step 5: Filter on a request header
Some providers put the event name in a header, not in the body. GitHub sends it as X-GitHub-Event, and Shopify sends the topic as X-Shopify-Topic. A condition reads a request header as @headers.<name>. A template reads it as {{@headers.<name>}}, including inside {{#each}}.
Write the name in lowercase: @headers.x-github-event. The bracket form @headers["x-github-event"] also works. An uppercase reference such as @headers.X-GitHub-Event is rejected when you test or deploy, with a message that gives the lowercase spelling. A header that is not on the request is empty, so @headers.x-github-event != "push" is true when the header is missing.
The hook sees the same headers Hooksmith stores with the event. Authorization, cookies, API key headers such as X-Api-Key, and proxy headers such as X-Forwarded-For are never visible, and neither is the header named in a verification.type: header check. A replay uses the stored headers, so it takes the same path as the original request.
The hook below keeps GitHub pushes and newly opened pull requests. The first condition drops every other event by its header. The second drops pull request actions other than opened, which only the body can tell. The template puts the event name from the header into the body your app receives.
.hooksmith/hooks/github-events.yamlapiVersion: hooksmith/v1 kind: Hook metadata: name: github-events description: GitHub pushes and opened pull requests only spec: source: preset: github destinations: - name: primary url: ${DESTINATION_URL} method: POST timeout: 8s retries: max: 3 backoff: exponential initialDelay: 500ms transform: engine: handlebars fields: event: "{{{@headers.x-github-event}}}" repo: "{{{repository.full_name}}}" url: "{{{default pull_request.html_url compare}}}" conditions: - if: '@headers.x-github-event != "push" && @headers.x-github-event != "pull_request"' then: skip: true - if: '@headers.x-github-event == "pull_request" && action != "opened"' then: skip: true variables: - name: GITHUB_WEBHOOK_SECRET from: secret - name: DESTINATION_URL from: secretpr-opened.json{ "action": "opened", "number": 42, "pull_request": { "title": "Fix retry backoff", "html_url": "https://github.com/acme/app/pull/42" }, "repository": { "full_name": "acme/app" } }terminalhooksmith new github-events --preset github --yes hooksmith test github-events --payload ./pr-opened.json --header "X-GitHub-Event: pull_request" hooksmith test github-events --payload ./pr-opened.json --header "X-GitHub-Event: issues"
Step 6: Store the secrets and deploy
Set the destination URL and the Stripe endpoint's signing secret, then deploy and paste the ingest URL into the Stripe endpoint. Deploy the GitHub hook the same way, with GITHUB_WEBHOOK_SECRET in place of the Stripe secret.
terminalhooksmith secrets set DESTINATION_URL printf %s "$WHSEC" | hooksmith secrets set STRIPE_WEBHOOK_SECRET hooksmith deploy stripe-failures
How to check it works
Confirm the filter on live traffic.
- hooksmith logs stripe-failures lists dropped events with the status skipped and delivered ones as delivered.
- On the hook's page, choose Send test event with the contents of drop.json. The dashboard answers: Skipped by a condition, followed by the if expression that matched. Nothing is delivered.
- Send the same test with pass.json. It is delivered to your destination for real.
- For the GitHub hook, send pr-opened.json with the header X-GitHub-Event: pull_request in the Headers box. It is delivered. Change the header to issues and it is skipped.
hooksmith logs stripe-failures
Troubleshooting
Every event is skipped.
Read reason: in the hooksmith test output. It is the if expression that matched. A condition that skips on type == "x" when you meant type != "x" drops exactly the events you want.
A condition never matches.
Compare against quoted strings. type == invoice.payment_failed compares type to another payload path, which is empty, not to the text.
A number comparison does not skip.
data.object.amount_due < 1000 is false when amount_due is missing, so the event is delivered. Add a second condition for the missing case if you want it dropped.
Unexpected character in condition: ...
The if expression has a character the parser does not know, for example a single =. hooksmith test prints the error before you deploy. The parser also reports Unterminated string in condition and Missing ).
A header condition skips every event, or never matches.
Write the header name in lowercase, as in @headers.x-github-event, and compare against a quoted string. In a test, pass the header: --header "X-GitHub-Event: push" for hooksmith test (CLI 0.6.4 or later) or the Headers box of Send test event. A header that is missing is empty, so != is true and == is false.
Header names are lowercase: use @headers.x-github-event instead of @headers.X-GitHub-Event
The condition or template uses an uppercase header name. Hooksmith stores header names in lowercase, so the uppercase spelling could never match. Use the lowercase spelling the message gives.
A header is always empty, although the sender sends it.
Hooksmith hides credentials and proxy metadata from the hook: Authorization, cookies, X-Api-Key, api-key, X-Auth-Token, X-Access-Token, X-Forwarded-*, X-Vercel-*, CF-*, and the header named in a verification.type: header check. Put what you need to filter on in a different header or in the body.
Stripe: signature mismatch
Hooksmith rejected the request before the filter ran. Set STRIPE_WEBHOOK_SECRET to the signing secret of the endpoint that points at this hook.
Related
- Stripe webhooks with HooksmithThe Stripe preset: verification, secrets and setup.
- GitHub webhooks with HooksmithThe GitHub preset skips events sent by bots, and its example filters by event header and branch.
- Forward Shopify webhooks to SlackShape what the event looks like once it passes.
- DocsHooks, secrets and limits.