Event Notifications

An event notification is a trigger plus a destination: it names what to watch for and where the result goes, which can be one or more email addresses, a webhook you host, or an endpoint you poll on your own schedule. This page is the procedure for creating one, testing it, and working out why one is not arriving.

You create and manage them in Settings, then Integrations, then Event notifications.

What do I need before I start?

• Write access to at least one environment. A read-only account can see notifications but cannot create a trigger or test a webhook.
• A decision about which environments' files should alert, and which environments' rules or reports should count as criteria. Read Triggers first if that distinction is not yet clear, because the wizard asks about both and the two are easy to confuse.
• For a webhook, a URL that accepts a POST with a JSON body and answers quickly. Stairwell gives up on a webhook that has not responded within a few seconds.

How do I create an event notification?

Select Create Event Notification and work through the three steps.

Step 1: Details. Name it something a colleague reading an alert at 3am will understand, because the name travels with every notification the trigger produces. Pick the organization, and pick the Object environments: the environments whose files are eligible to alert. If you administer other organizations, note that the notification inherits the permissions of the organization you select here.

Step 2: Conditions. Select the conditions to monitor. They come in two groups because they behave differently.

Rule and report matching, which can span your own environments and the global malware corpus:

• YARA rule match. Fires when a rule from the rule source environments you pick matches a file in the object environments. Stairwell's own research rule environments are the usual choice, plus any environment where your team writes rules. Picking only an environment with no rules in it gives you a trigger that never fires.
• Threat report indicator match. Fires when an indicator from a report in the report source environments you pick links to a file in the object environments. The default source is where the reports Stairwell supplies arrive, and it is the right answer unless you have set up your own.

Threat detection, which monitors your own environments only:

• High confidence MalEval score. Fires when the automated verdict for a file reaches high confidence malicious.
• Objects marked malicious. Fires on an opinion of Malicious, both when one is recorded and when a file already carrying one turns up in a watched environment.

If you leave a global malware corpus environment selected in step 1 while either threat detection condition is checked, saving fails and names the environment to remove. Remove it, or deselect those two conditions.

Step 3: Destinations. Choose Email, Webhook, or API, then fill in what it asks for. Select Test if you chose a webhook, then Save.

Which destination should I choose?

• Email for a human reading it. Give one or more addresses. The message renders the file, its hashes, where it was seen, and which criterion matched, with links back into the product.
• Webhook for anything automated: a SOAR platform, a SIEM, a chat channel, a script of your own. You supply the URL and pick a payload version.
• API when you would rather pull than be pushed. Nothing is sent anywhere; the matches accumulate and you read them with GET /v1/environments/{environment}/triggerMatches, optionally bounded with filter.oldestTime and filter.newestTime and paged with pageSize and pageToken. Choose this when your network will not accept an inbound webhook, or when you want to control the rate.

Webhook payload versions:

How do I send notifications to Slack?

Create an incoming webhook in Slack, then paste its URL as the webhook URI. Stairwell recognizes a Slack webhook URL and switches the version to Slack JSON for you. Select Test, confirm the message lands in the channel, and save.

How do I check that it works?

For a webhook, Test sends an example payload in the version you selected to the URL you entered, and reports the HTTP status your endpoint returned. A 2xx means your endpoint accepted the shape. It does not prove your parsing is right, so read the test message on the receiving side once, at least for a new integration.

After saving, the trigger takes effect within a couple of minutes rather than instantly. The same delay applies to every edit.

For any destination, the record of what fired is on the Alerts page in the left navigation, whether or not delivery succeeded. That is the place to check first when someone says a notification never arrived, because it separates "Stairwell did not fire" from "the delivery did not land".

How do I send notifications to Google SecOps?

Append your key and secret to the webhook URI as query parameters, so the URI ends in the form .../ImportPushLogs?key=xxxx&secret=yyyy. Then parse the payload on the SecOps side with:

filter {
  json {
    source => "message"
    target => "event"
    on_error => "json_failure"
    array_function => "split_columns"
  }
  statedump{}
}

How do I edit or delete one?

The Event notifications table lists each trigger with its name, destination type, destination, and how many conditions it carries. The row's controls edit or delete it. Editing reopens the same three steps with your answers filled in.

Deleting a trigger stops future notifications and leaves the ones it already produced on the Alerts page.

Why am I not getting notifications?

Work down this list in order. Each of these is a real cause, and the first three account for most of it.

1. The condition has no criteria behind it. A YARA rule condition pointed at environments containing no rules, or a report condition pointed at an environment with no reports, is a valid trigger that can never fire. Reopen step 2 and check the source environments.
2. Someone marked the file safe. An opinion of Trusted or Benign suppresses notifications for that file. The scope is wider than people expect, and Trigger Silences describes it precisely.
3. A silence is in place. Silences are invisible in the notification stream by design. Same page.
4. The file has been seen there before. A file reappearing at a location it has already been seen at does not notify again. A genuinely new asset or path does.
5. The verdict already fired recently. Verdict-driven notifications for the same file and trigger are suppressed for twenty-four hours.
6. Delivery failed. If the alert is on the Alerts page but did not reach your endpoint, the problem is on the delivery side: a URL that has moved, an endpoint too slow to answer, an auth header your receiver now rejects. Retest the webhook.
7. It is older than the retention window. Notifications are kept for 180 days. Anything you need beyond that should be pulled into your own system as it arrives.

If you have worked through all of that and the arithmetic still does not add up, send the file's hash, the trigger name, and roughly when you expected the alert to [email protected]. Every notification decision is recorded, including the suppressions, so support can tell you exactly which gate the alert met and why.

What should I read next?

• Triggers, for what each match type means and why a trigger fires on an old file.
• Trigger Silences, for turning down volume without turning off a detection.
• Verdicts, the automated conclusion behind the threat detection conditions.