PushizoDocs
SDK guides

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

ParameterDefaultDescription
api_key:—hs_live_… API key (Bearer)
app_id:nilApp used when a call doesn't pass app_id:
base_url:https://api.pushizo.comAPI URL
timeout:30Timeout per attempt (s)
max_retries:3Maximum retries (policy)
auto_idempotency_key:trueAutomatic UUID on calls that support Idempotency-Key
transport:NetHttpTransportCustom 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}"
end

Retry 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:

ConditionGET, HEAD, OPTIONS, PUT, DELETEPOST, PATCH
429RetriedRetried (the request was rejected before processing)
5xx, timeout, connection dropped after sendingRetriedOnly with an Idempotency-Key
Request never sent (SocketError (DNS), Errno::ECONNREFUSED, Errno::EHOSTUNREACH/ENETUNREACH, Net::OpenTimeout)RetriedRetried
Other 4xxNot retriedNot 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
end

If 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/

On this page