Ruby SDK

The zeridion-flare gem is published on RubyGems. Zero runtime dependencies — uses stdlib Net::HTTP, OpenSSL, and JSON only.

gem install zeridion-flare

Or add to your Gemfile:

gem "zeridion-flare", "~> 0.1.1"

The ~> 0.1.1 pessimistic-version operator allows patch upgrades (0.1.2, 0.1.3, ...) but holds you on the 0.1.x line — recommended while the SDK is pre-1.0 and a minor bump may carry breaking changes.

Requires: Ruby 3.1+.

Quick start

require "zeridion_flare"

client = Zeridion::Flare::Client.new(api_key: "zf_live_sk_...")
# Or, with FLARE_API_KEY set in the environment:
#   client = Zeridion::Flare::Client.new

job = client.create_job(
  "job_type" => "SendWelcomeEmail",
  "payload"  => { "email" => "alice@example.com" },
  "queue"    => "default",
)

puts job["id"], job["state"]  # "job_abc123", "pending"

Every public method accepts optional idempotency_key: and request_id: keyword arguments, sent as the Idempotency-Key and X-Request-Id headers respectively:

idempotency_key: — semantic deduplication on the server. A second create_job with the same key returns the original response (status code and body), not a fresh write.
request_id: — log-correlation hint. Pass your application's trace / correlation ID and grep for it in Zeridion's logs. Omit it and the server returns a generated ULID in the response X-Request-Id header.

Client construction

Keyword	Default	Notes
`api_key:`	`ENV["FLARE_API_KEY"]`	Required — pass directly or via env var
`base_url:`	`https://api.zeridion.com`	Override for dev / staging
`max_retries:`	`3`	Set `0` to disable retries
`retry_base_delay_ms:`	`500`	Base for exponential schedule
`retry_max_delay_ms:`	`30_000`	Cap on a single backoff wait (and on `Retry-After`)
`timeout_seconds:`	`30`	Per-request timeout
`max_response_bytes:`	`10 * 1024 * 1024` (10 MiB)	Hard cap on response body size; protects against an unbounded body. Set `0` to disable.

Typed error hierarchy

Class	HTTP	When it fires
`Zeridion::Flare::Error`	—	Base class for every SDK exception
`Zeridion::Flare::AuthError`	401	Missing / invalid / revoked API key
`Zeridion::Flare::QuotaError`	402	Billing state blocked — subscription `past_due` / `unpaid` / `cancelled`
`Zeridion::Flare::NotFoundError`	404	Resource doesn't exist
`Zeridion::Flare::ConflictError`	409	Idempotency or invalid-state conflict
`Zeridion::Flare::RateLimitError`	429	Inspect `#retry_after`, `#limit`, `#remaining`

Webhook verification

Zeridion::Flare::Webhook.verify validates the X-Zeridion-Signature header on outbound webhook deliveries. Pass the raw request body — re-encoding parsed JSON invalidates the signature.

require "zeridion_flare"

post "/hooks/zeridion" do
  payload = request.body.read
  header  = request.env["HTTP_X_ZERIDION_SIGNATURE"].to_s

  unless Zeridion::Flare::Webhook.verify(payload, header, webhook_secret, tolerance_seconds: 300)
    halt 400
  end

  # Safe to process the event.
  200
end

tolerance_seconds: enables replay protection — deliveries whose signature timestamp drifts more than that many seconds from the current time are rejected (recommended: 300; default nil = no timestamp check). The helper verifies against every v1= digest in the header, so it keeps working through a secret rotation with no receiver change.

Feature parity

See the SDK overview for the full feature-parity matrix across all 7 official SDKs.

Source

github.com/zeridion/flare-ruby

Quick start​

Client construction​

Typed error hierarchy​

Webhook verification​

Feature parity​

Source​

See also​