Ruby SDK
pushizo (RubyGems) — Ruby 3.0+, Net::HTTP; generated models and resource methods, retries, idempotency, Enumerator pagination, webhook signature verification.
Source: sdk/ruby. Models and resource methods are generated from api/openapi.yaml (lib/pushizo/generated/); authentication, retries, idempotency, pagination, and webhook signature verification are hand-written. There are no runtime dependencies.
Installation
# Gemfile
gem "pushizo"Usage
require "pushizo"
hs = Pushizo::Client.new(api_key: ENV.fetch("HS_API_KEY"), app_id: "app_…") # locally: base_url: "http://localhost:4000"
# Send a notification: automatic UUID if no Idempotency-Key is given
res = hs.notifications.create(
{
target: { include_aliases: { external_id: ["user-42"] } },
contents: { en: "Your order shipped", tr: "Siparişiniz kargoya verildi" }
},
idempotency_key: "order-1001"
)
puts res.id, res.status
# Create/update a user (accepts a Hash or a model object)
hs.users.upsert(Pushizo::Models::UpsertUserDto.new(external_id: "user-42", tags: { plan: "pro" }))
# Cursor pagination: Enumerator, pages are loaded lazily
hs.segments.list_all(limit: 100).each { |segment| puts segment.name }
# A single call for a different app
hs.apps.get(app_id: "app_diger")
# SDK identity verification
identity_hash = Pushizo.identity_hash(ENV.fetch("HS_SDK_SECRET"), "user-42")Responses are Pushizo::Models::* objects: access fields with snake_case methods (msg.status) or with msg["status"]; to_h returns the raw hash with JSON names. Resources: hs.notifications, hs.users, hs.aliases, hs.subscriptions, hs.events, hs.channels, hs.segments, hs.templates, hs.campaigns, hs.journeys, hs.in_app_messages, hs.inbox, hs.categories, hs.preferences, hs.suppressions, hs.webhooks, hs.analytics, hs.exports, hs.imports, hs.api_keys, hs.apps, hs.organization. To avoid clashing with Object#send, events.send is named send_events and campaigns.send is named send_campaign. A/B winner: campaigns.select_winner, in_app_messages.select_winner (in_app_messages.winner is the old name and is deprecated). For endpoints without an SDK method or for non-JSON responses, use hs.request(:get, "/v1/apps/{appId}/analytics/messages", query: { format: "csv" }).
Settings
| Parameter | Default | Description |
|---|---|---|
api_key: | — | hs_live_… API key (Bearer) |
app_id: | nil | App used when a call doesn't pass app_id: |
base_url: | https://api.pushizo.com | API URL |
timeout: | 30 | Timeout per attempt (s) |
max_retries: | 3 | Maximum retries (policy) |
auto_idempotency_key: | true | Automatic UUID on calls that support Idempotency-Key |
transport: | NetHttpTransport | Custom transport (#call(method, url, headers, body, timeout)) |
You can also configure each call with request_options: { timeout: 5, max_retries: 0, headers: { … } }.
Errors
Permanent errors are subclasses of Pushizo::Error: status, code, request_id, details.
begin
hs.notifications.get("msg_yok")
rescue Pushizo::NotFoundError
# 404
rescue Pushizo::InvalidRequestError => e
# 400/422 — e.code == Pushizo::ErrorCode::NO_RECIPIENTS
rescue Pushizo::Error => e
# AuthenticationError, PermissionDeniedError, ConflictError, RateLimitError, ServerError, NetworkError
warn "#{e.status} #{e.code} #{e.message}"
endRetry policy
Retries use exponential backoff (0.3 / 1 / 3 s; the Retry-After header is honored when present) and run at most max_retries: times. To avoid double-processing requests that aren't safe to repeat on the server, the rule depends on the HTTP method:
| Condition | GET, HEAD, OPTIONS, PUT, DELETE | POST, PATCH |
|---|---|---|
429 | Retried | Retried (the request was rejected before processing) |
5xx, timeout, connection dropped after sending | Retried | Only with an Idempotency-Key |
Request never sent (SocketError (DNS), Errno::ECONNREFUSED, Errno::EHOSTUNREACH/ENETUNREACH, Net::OpenTimeout) | Retried | Retried |
Other 4xx | Not retried | Not retried |
On a 5xx or a network error after sending, the server may have processed the request; retrying a POST/PATCH without a key can produce a duplicate notification or record. notifications.create and users.upsert generate an automatic UUID when no key is given (unless automatic keys are disabled), so these two calls are safe to retry. If you want another POST/PATCH call to be retried as well, pass the key yourself: hs.events.send_events(body, request_options: { idempotency_key: "evt-#{id}" }). Retries send the same key; the API answers a repeat with the same key within 24 hours with the original response.
Webhook signature verification
# Rails
class PushizoWebhooksController < ActionController::API
def create
events = Pushizo::Webhook.construct_events(
request.raw_post, # raw body
request.headers["Pushizo-Signature"],
ENV.fetch("HS_WEBHOOK_SECRET") # during rotation you can pass [old, new]
)
events.each { |event| } # single or batch; deduplicate using event["id"]
head :no_content
rescue Pushizo::WebhookSignatureError => e
render plain: e.reason, status: :bad_request
end
endIf the timestamp is older than 5 minutes (tolerance:), the request is treated as a replay. For verification only, Pushizo::Webhook.verify_signature(...) returns ok?, timestamp, and reason. Event types: Webhooks.
Development
rake test # inside sdk/ruby
node sdk/scripts/generate-server-sdks.mjs --lang ruby # at the repo root; regenerates generated/.NET SDK
Pushizo (NuGet) — .NET 8, HttpClient and System.Text.Json; generated models and resources, retries, idempotency, IAsyncEnumerable pagination, webhook signature verification.
Rust SDK
The pushizo crate on crates.io — Rust 1.71+, ureq; models and services generated from OpenAPI, retries, idempotency, pagination, webhook signature verification.