perchfall-notify

Notification channels for Perchfall synthetic monitoring. Get alerted in Slack — or anywhere you like — the moment a check fails.

slack = Perchfall::Notify::Channels::Slack.new(
  webhook_url: ENV["SLACK_WEBHOOK_URL"]
)

report = Perchfall.run(url: "https://example.com")
Perchfall::Notify.deliver(report, channels: [slack])

Why perchfall-notify

Perchfall tells you what a real browser saw. perchfall-notify tells your team about it.

Fail-open delivery — if one channel errors, the others still fire. A Slack outage won't suppress your SMS alert.
Ships with Slack — Block Kit messages with status, URL, HTTP code, duration, and a full list of network and console errors.
Bring your own channel — implement one method and plug anything in: webhooks, PagerDuty, SMS, email.
No framework required — works in Sidekiq jobs, Rake tasks, plain Ruby scripts, or anywhere Perchfall runs.

Requirements

Dependency	Version
Ruby	≥ 3.2
perchfall	≥ 0.3.0

Installation

bundle add perchfall-notify

Quickstart

require "perchfall/notify"

slack = Perchfall::Notify::Channels::Slack.new(
  webhook_url: ENV["SLACK_WEBHOOK_URL"]
)

report = Perchfall.run(url: "https://example.com")

Perchfall::Notify.deliver(report, channels: [slack])

That's it. If the report has network errors or console errors, they'll appear in the Slack message.

Slack channel

Create a Slack incoming webhook and pass the URL:

slack = Perchfall::Notify::Channels::Slack.new(
  webhook_url: "https://hooks.slack.com/services/..."
)

The default message format uses Block Kit and includes:

Pass/fail header with optional scenario name
URL, HTTP status, and duration
Network errors with method, URL, and failure reason
Console errors with type and message

Custom message format

Inject a formatter to control message shape:

class MyFormatter
  def format(report)
    {
      text: report.ok? ? "✅ #{report.url} OK" : "🚨 #{report.url} FAILED"
    }
  end
end

slack = Perchfall::Notify::Channels::Slack.new(
  webhook_url: ENV["SLACK_WEBHOOK_URL"],
  formatter: MyFormatter.new
)

Delivering to multiple channels

Pass any number of channels. All are attempted — a failure in one does not skip the others.

Perchfall::Notify.deliver(report, channels: [slack, pagerduty, sms])

If any channels fail, a single Perchfall::Notify::DeliveryError is raised after all have been attempted, with a summary of every failure.

Building a custom channel

Subclass Perchfall::Notify::Channel and implement #deliver:

class WebhookChannel < Perchfall::Notify::Channel
  def initialize(url)
    @url = url
  end

  def deliver(report)
    # post report.to_json to @url
  rescue => e
    raise Perchfall::Notify::DeliveryError, "Webhook failed: #{e.message}"
  end
end

Raise DeliveryError on failure so Notifier can accumulate it alongside other channel failures.

Use in a background job

class SyntheticCheckJob
  include Sidekiq::Job

  def perform(url)
    channels = [
      Perchfall::Notify::Channels::Slack.new(webhook_url: ENV.fetch("SLACK_WEBHOOK_URL"))
    ]
    report = Perchfall.run(url: url)
    Perchfall::Notify.deliver(report, channels: channels)
  rescue Perchfall::Errors::PageLoadError => e
    Perchfall::Notify.deliver(e.report, channels: channels)
  end
end

Errors

Exception	When
`Perchfall::Notify::ConfigurationError`	A channel was constructed with invalid configuration (e.g. missing webhook URL)
`Perchfall::Notify::DeliveryError`	One or more channels failed to deliver
`Perchfall::Notify::Error`	Base class — catches any perchfall-notify error

Development

bundle install
bundle exec rspec
bin/console

License

MIT