> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ruby.ad/llms.txt
> Use this file to discover all available pages before exploring further.

# Filter webhooks payload

> Decide which events from a webhook should run your agent: in plain language for most sources, or with a filter expression for custom webhooks.

Most webhook triggers don't need anything below: describe the condition in plain language and Ruby writes the filter for you. This page is only for **custom webhooks**, which have no connected provider, so Ruby can't generate a filter automatically and you write one yourself.

## Most webhooks: describe it in plain language

For a trigger on a built-in source (GitHub, Jira, Linear, Zendesk, Fathom), the trigger sheet has a **Run only when** (optional) field. Describe the condition in plain English, for example *"Pull requests by John on ruby repository"*, and Ruby generates the filter for you. Leave it blank and the trigger runs on every event the source sends.

## Custom webhooks: write a filter expression

A custom webhook has no provider, so Ruby doesn't know the shape of its payload and can't offer the plain-language option. Instead, the trigger sheet has a **Filter expression** (optional) field. Leave it blank and every request runs the agent; write an expression and only matching requests do.

### How it works

An expression is a small rule written as `(operator "field.path" value)`. Field paths use dot notation into the JSON payload the webhook sends, for example `"issue.state"` or `"pull_request.head.ref"`. For an array of objects, pull one field out of each item with a single wildcard level: `"tags.*.name"` reads `name` from every object in `tags` (deeper paths like `"tags.*.sub.name"` aren't supported).

Combine rules with `and`, `or`, and `not`:

```
(and
  (eq "action" "opened")
  (eq "issue.state" "open"))
```

### Operators

| Operator | Checks | Example |
| - | - | - |
| `eq` | exact match (string, number, or boolean) | `(eq "action" "opened")` |
| `starts-with` | string starts with a prefix | `(starts-with "pull_request.head.ref" "feature/")` |
| `contains` | string contains a substring | `(contains "issue.title" "urgent")` |
| `has` | array contains a value | `(has "issue.labels" "bug")` |
| `has-all` | array contains every listed value | `(has-all "issue.labels" ("bug" "critical"))` |
| `has-any` | array contains at least one listed value | `(has-any "issue.labels" ("bug" "critical"))` |
| `gt` / `gte` | number greater than / or equal to | `(gt "issue.comments" 10)` |
| `lt` / `lte` | number less than / or equal to | `(lt "issue.comments" 3)` |
| `exists` | field is present and not null | `(exists "issue.milestone")` |
| `and` / `or` / `not` | combine or negate rules | `(and (eq "a" 1) (eq "b" 2))` |

### Examples

* Only opened issues: `(eq "action" "opened")`
* Opened by a specific person: `(and (eq "action" "opened") (eq "sender.login" "alice"))`
* Has a "bug" or "urgent" label: `(has-any "issue.labels" ("bug" "urgent"))`
* Not closed (combine `not` and `eq`): `(not (eq "issue.state" "closed"))`
* Large pull requests: `(and (eq "action" "opened") (gt "pull_request.changed_files" 20))`

## Test before you save

Click **Compute stats** next to the filter field. Ruby looks at the last 24 hours of events this source received and reports how many would have matched your filter. You need at least 10 events in that window for an estimate; with fewer, it shows "not enough data" instead. Use it to confirm your filter catches what you expect before turning the trigger on.

## Common mistakes

* **Case matters.** `"issue.State"` is a different field from `"issue.state"`, and `(eq "action" "Opened")` won't match a payload where `action` is `"opened"`.
* **Numeric operators need real numbers.** `(gt "issue.comments" "10")` always returns `false` if `"10"` is written as a quoted string; `gt`, `gte`, `lt`, and `lte` only work when both sides are JSON numbers.
* **Wildcards go one level deep.** `"tags.*.name"` works; `"tags.*.sub.name"` does not.
* **An empty expression always runs.** Leave **Filter expression** blank and the trigger fires on every event from that source.
* **A missing field just means "false", not an error.** Any check on a field the payload doesn't have returns `false`, except `(not (exists "field"))`, which returns `true`.
* **An empty list in `has-all` is trivially true.** `(has-all "issue.labels" ())` returns `true`, there are no required values left to fail on. `has-any` with an empty list behaves as you'd expect and returns `false`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.