jobcelis
Official Ruby SDK for the Jobcelis Event Infrastructure Platform.
All API calls go to https://jobcelis.com by default -- you only need your API key to get started.
Installation
Add to your Gemfile:
gem "jobcelis"Then run:
bundle installOr install directly:
gem install jobcelisQuick Start
require "jobcelis"
# Only your API key is required -- connects to https://jobcelis.com automatically
client = Jobcelis::Client.new(api_key: "your_api_key")Custom URL: If you're self-hosting Jobcelis, you can override the base URL:
client = Jobcelis::Client.new(api_key: "your_api_key", base_url: "https://your-instance.example.com")
Authentication
The auth methods do not require an API key. Use them to register, log in, and manage JWT tokens.
require "jobcelis"
client = Jobcelis::Client.new(api_key: "")
# Register a new account
user = client.register(email: "alice@example.com", password: "SecurePass123!", name: "Alice")
# Log in -- returns JWT access token and refresh token
session = client.login(email: "alice@example.com", password: "SecurePass123!")
access_token = session["token"]
refresh_tok = session["refresh_token"]
# Set the JWT for subsequent authenticated calls
client.set_auth_token(access_token)
# Refresh an expired token
new_session = client.refresh_token(refresh_tok)
client.set_auth_token(new_session["token"])
# Verify MFA (requires Bearer token already set)
result = client.verify_mfa(token: access_token, code: "123456")Events
# Send a single event
event = client.send_event("order.created", { order_id: "123", amount: 99.99 })
# Send batch events (up to 1000)
batch = client.send_events([
{ topic: "order.created", payload: { order_id: "1" } },
{ topic: "order.created", payload: { order_id: "2" } },
])
# List events with pagination
events = client.list_events(limit: 25)
next_page = client.list_events(limit: 25, cursor: events["cursor"])
# Get / delete a single event
event = client.get_event("evt_abc123")
client.delete_event("evt_abc123")Simulate
# Dry-run an event to see which webhooks would fire
result = client.simulate_event("order.created", { order_id: "test" })Webhooks
# Create a webhook
webhook = client.create_webhook(
url: "https://example.com/webhook",
topics: ["order.*"],
)
# List, get, update, delete
webhooks = client.list_webhooks
wh = client.get_webhook("wh_abc123")
client.update_webhook("wh_abc123", url: "https://new-url.com/hook")
client.delete_webhook("wh_abc123")
# Health and templates
health = client.webhook_health("wh_abc123")
templates = client.webhook_templatesDeliveries
deliveries = client.list_deliveries(limit: 20, status: "failed")
client.retry_delivery("del_abc123")Dead Letters
dead_letters = client.list_dead_letters
dl = client.get_dead_letter("dlq_abc123")
client.retry_dead_letter("dlq_abc123")
client.resolve_dead_letter("dlq_abc123")Replays
replay = client.create_replay(
topic: "order.created",
from_date: "2026-01-01T00:00:00Z",
to_date: "2026-01-31T23:59:59Z",
webhook_id: "wh_abc123", # optional
)
replays = client.list_replays
r = client.get_replay("rpl_abc123")
client.cancel_replay("rpl_abc123")Scheduled Jobs
# Create a job
job = client.create_job(
name: "daily-report",
queue: "default",
cron_expression: "0 9 * * *",
payload: { type: "daily" },
)
# CRUD
jobs = client.list_jobs(limit: 10)
job = client.get_job("job_abc123")
client.update_job("job_abc123", cron_expression: "0 10 * * *")
client.delete_job("job_abc123")
# List runs for a job
runs = client.list_job_runs("job_abc123", limit: 20)
# Preview cron schedule
preview = client.cron_preview("0 9 * * *", count: 10)Pipelines
pipeline = client.create_pipeline(
name: "order-processing",
topics: ["order.created"],
steps: [
{ type: "filter", config: { field: "amount", gt: 100 } },
{ type: "transform", config: { add_field: "priority", value: "high" } },
],
)
pipelines = client.list_pipelines
p = client.get_pipeline("pipe_abc123")
client.update_pipeline("pipe_abc123", name: "order-processing-v2")
client.delete_pipeline("pipe_abc123")
# Test a pipeline with a sample payload
result = client.test_pipeline("pipe_abc123", { topic: "order.created", payload: { id: "1" } })Event Schemas
schema = client.create_event_schema(
topic: "order.created",
schema: {
type: "object",
properties: {
order_id: { type: "string" },
amount: { type: "number" },
},
required: ["order_id", "amount"],
},
)
schemas = client.list_event_schemas
s = client.get_event_schema("sch_abc123")
client.update_event_schema("sch_abc123", schema: { type: "object" })
client.delete_event_schema("sch_abc123")
# Validate a payload against a topic's schema
result = client.validate_payload("order.created", { order_id: "123", amount: 50 })Sandbox
# Create a temporary endpoint for testing
endpoint = client.create_sandbox_endpoint(name: "my-test")
endpoints = client.list_sandbox_endpoints
# Inspect received requests
requests = client.list_sandbox_requests("sbx_abc123", limit: 20)
client.delete_sandbox_endpoint("sbx_abc123")Analytics
events_chart = client.events_per_day(days: 30)
deliveries_chart = client.deliveries_per_day(days: 7)
topics = client.top_topics(limit: 5)
stats = client.webhook_statsProject and Token Management
# Current project
project = client.get_project
client.update_project(name: "My Project v2")
# Topics
topics = client.list_topics
# API token
token = client.get_token
new_token = client.regenerate_token
# Limit the token to scopes and client IPs (empty allowed_ips = any IP)
client.update_token_restrictions(scopes: ["events:read", "events:write"], allowed_ips: ["203.0.113.10"])Multi-Project Management
projects = client.list_projects
new_project = client.create_project("staging-env")
p = client.get_project_by_id("proj_abc123")
client.update_project_by_id("proj_abc123", name: "production-env")
client.set_default_project("proj_abc123")
client.delete_project("proj_abc123")Team Members
members = client.list_members("proj_abc123")
member = client.add_member("proj_abc123", email: "alice@example.com", role: "admin")
client.update_member("proj_abc123", "mem_abc123", role: "viewer")
client.remove_member("proj_abc123", "mem_abc123")Invitations
# List pending invitations
invitations = client.list_pending_invitations
# Accept or reject
client.accept_invitation("inv_abc123")
client.reject_invitation("inv_def456")Audit Logs
logs = client.list_audit_logs(limit: 100)
next_page = client.list_audit_logs(cursor: logs["cursor"])Data Export
Export methods return raw strings (CSV or JSON).
# Export as CSV
csv_data = client.export_events(format: "csv")
File.write("events.csv", csv_data)
# Export as JSON
json_data = client.export_deliveries(format: "json")
# Other exports
client.export_jobs(format: "csv")
client.export_audit_log(format: "csv")GDPR / Privacy
# Consent management
consents = client.get_consents
client.accept_consent("marketing")
# Data portability
my_data = client.export_my_data
# Processing restrictions
client.restrict_processing
client.lift_restriction
# Right to object
client.object_to_processing
client.restore_consentHealth Check
health = client.health
status = client.statusError Handling
require "jobcelis"
client = Jobcelis::Client.new(api_key: "your_api_key")
begin
event = client.get_event("nonexistent")
rescue Jobcelis::Error => e
puts "Status: #{e.status}" # 404
puts "Detail: #{e.detail}" # {"message"=>"Not found"}
endRetries
The client retries a request automatically when the connection fails (refused or reset connection, DNS or TLS failure, timeout) or the API answers 429, 502, 503 or 504, for example while Jobcelis is being deployed. It waits 1 s, 2 s, 4 s, 8 s, 16 s and 30 s between attempts (with ±20 % jitter), or what the Retry-After header asks for, up to 60 s. By default it makes up to 6 retries, about 60 s in total. Other errors, such as 400 or 500, are raised immediately as Jobcelis::Error; after the last retry you get the same error you would get without retries.
GET, PUT, PATCH and DELETE are retried in all of these cases. POST is retried on 429/502/503/504, and after a connection failure only when it carries an idempotency key, so a request can never be applied twice:
-
send_eventsends anX-Idempotency-Keyheader, the same on every retry. Passidempotency_key:to use your own key; otherwise a UUID is generated. -
send_eventsadds anidempotency_keyto every event that does not have one.
Change or disable retries when you create the client:
client = Jobcelis::Client.new(api_key: "your_api_key", max_retries: 3)
client = Jobcelis::Client.new(api_key: "your_api_key", max_retries: 0) # no retriesWebhook Signature Verification
require "jobcelis"
# Sinatra example
post "/webhook" do
body = request.body.read
signature = request.env["HTTP_X_SIGNATURE"]
unless Jobcelis::WebhookVerifier.verify(
secret: "your_webhook_secret",
body: body,
signature: signature
)
halt 401, "Invalid signature"
end
event = JSON.parse(body)
puts "Received: #{event['topic']}"
status 200
"OK"
endLicense
BSL-1.1 (Business Source License)
Releasing
Merge to main: the Release workflow publishes every change to the package as the next patch version (1.3.1 → 1.3.2) to RubyGems, writes the version into jobcelis.gemspec and lib/jobcelis.rb and tags the commit. Changes to docs, tests or CI publish nothing. For a minor or major version, raise it in jobcelis.gemspec and lib/jobcelis.rb in the same pull request. Every pull request runs CI, which runs the tests (ruby -Ilib -Itest -e 'Dir["test/**/*_test.rb"].each { |f| require File.expand_path(f) }').