Skip to content

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

  1. 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.

    terminal
    hooksmith init
    hooksmith new stripe-failures --preset stripe --yes
  2. 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.

  3. 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.yaml
    apiVersion: 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: secret
    
  4. Step 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" } }
    }
    terminal
    hooksmith test stripe-failures --payload ./drop.json
    hooksmith test stripe-failures --payload ./pass.json
    output for drop.json
    payload: ./drop.json
    skipped: true
    reason: type != "invoice.payment_failed" && type != "charge.dispute.created"
    output for pass.json
    payload: ./pass.json
    skipped: false
    destinations: primary
    body:
    {
      "id": "evt_1",
      "type": "invoice.payment_failed",
      "data": {
        "object": {
          "id": "in_1",
          "amount_due": 4900,
          "currency": "usd"
        }
      }
    }
  5. 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.yaml
    apiVersion: 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: secret
    
    pr-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" }
    }
    terminal
    hooksmith 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"
  6. 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.

    terminal
    hooksmith 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.
terminal
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.