.NET SDK
Pushizo (NuGet) — .NET 8, HttpClient and System.Text.Json; generated models and resources, retries, idempotency, IAsyncEnumerable pagination, webhook signature verification.
Source: sdk/dotnet. Models (Pushizo.Models), parameter classes (Pushizo.Params), and resources (Pushizo.Resources) are generated from api/openapi.yaml (src/Pushizo/Generated/); authentication, retries, idempotency, pagination, and webhook signature verification are hand-written. There are no additional dependencies.
Installation
dotnet add package PushizoUsage
using Pushizo;
using Pushizo.Models;
using Pushizo.Params;
using var hs = new PushizoClient(new PushizoOptions
{
ApiKey = Environment.GetEnvironmentVariable("HS_API_KEY")!,
AppId = "app_…",
// BaseUrl = "http://localhost:4000",
});
// Send a notification: automatic UUID if no Idempotency-Key is given
var res = await hs.Notifications.CreateAsync(new CreateNotificationDto
{
Target = new CreateNotificationDtoTarget { IncludeAliases = new() { ["external_id"] = new() { "user-42" } } },
Contents = new() { ["en"] = "Your order shipped", ["tr"] = "Siparişiniz kargoya verildi" },
}, new RequestOptions { IdempotencyKey = "order-1001" });
Console.WriteLine($"{res.Id} {res.Status}");
// Create/update a user
await hs.Users.UpsertAsync(new UpsertUserDto { ExternalId = "user-42", Tags = new() { ["plan"] = "pro" } });
// Cursor pagination: IAsyncEnumerable, pages are loaded lazily
await foreach (var segment in hs.Segments.ListAllAsync(new SegmentsListParams { Limit = 100 }))
{
Console.WriteLine(segment.Name);
}
// A single call for a different app
await hs.Apps.GetAsync(RequestOptions.ForApp("app_diger"));
// SDK identity verification
var identityHash = PushizoClient.IdentityHash(Environment.GetEnvironmentVariable("HS_SDK_SECRET")!, "user-42");In ASP.NET Core with IHttpClientFactory: new PushizoOptions { ApiKey = …, HttpClient = factory.CreateClient("pushizo") }. All model properties are nullable; null fields aren't sent. Resources: hs.Notifications, hs.Users, hs.Aliases, hs.Subscriptions, hs.Events, hs.Channels, hs.Segments, hs.Templates, hs.Campaigns, hs.Journeys, hs.InAppMessages, hs.Inbox, hs.Categories, hs.Preferences, hs.Suppressions, hs.Webhooks, hs.Analytics, hs.Exports, hs.Imports, hs.ApiKeys, hs.Apps, hs.Organization; every method has the …Async suffix and accepts RequestOptions and a CancellationToken. A/B winner: hs.Campaigns.SelectWinnerAsync, hs.InAppMessages.SelectWinnerAsync (InAppMessages.WinnerAsync is the old name, [Obsolete]). For endpoints without an SDK method or for non-JSON responses, hs.RequestAsync("GET", "/v1/apps/{appId}/analytics/messages", new Dictionary<string, object?> { ["format"] = "csv" }) returns the body as text.
Settings
PushizoOptions | Default | Description |
|---|---|---|
ApiKey | — | hs_live_… API key (Bearer) |
AppId | — | App used when a call doesn't pass RequestOptions.AppId |
BaseUrl | https://api.pushizo.com | API URL |
Timeout | 30 s | Timeout per attempt |
MaxRetries | 3 | Maximum retries (policy) |
AutoIdempotencyKey | true | Automatic UUID on calls that support Idempotency-Key |
HttpClient | new instance | Custom HttpClient |
Errors
Permanent errors are subclasses of PushizoException: Status, Code, RequestId, Details.
try
{
await hs.Notifications.GetAsync("msg_yok");
}
catch (NotFoundException) { /* 404 */ }
catch (InvalidRequestException e) when (e.Code == ErrorCodes.NoRecipients) { /* 422 */ }
catch (PushizoException e) { Console.WriteLine($"{e.Status} {e.Code} {e.Message}"); }
// Other subclasses: AuthenticationException, PermissionDeniedException, ConflictException, RateLimitException, ServerException, NetworkExceptionRetry policy
Retries use exponential backoff (0.3 / 1 / 3 s; the Retry-After header is honored when present) and run at most MaxRetries 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 (HttpRequestError.NameResolutionError/ConnectionError, SocketError.ConnectionRefused/HostNotFound/HostUnreachable) | 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.CreateAsync and Users.UpsertAsync 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: await hs.Events.SendAsync(body, new RequestOptions { IdempotencyKey = $"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
app.MapPost("/hooks/pushizo", async (HttpRequest request) =>
{
using var ms = new MemoryStream();
await request.Body.CopyToAsync(ms); // raw body
try
{
var events = Webhooks.ConstructEvents(ms.ToArray(),
request.Headers[Webhooks.SignatureHeader],
new[] { Environment.GetEnvironmentVariable("HS_WEBHOOK_SECRET")! }); // during rotation: old + new secret
foreach (var ev in events) { /* deduplicate using ev.Id; ev.Type, ev.Data */ }
return Results.NoContent();
}
catch (WebhookSignatureException e)
{
return Results.BadRequest(e.Reason);
}
});For verification only, Webhooks.VerifySignature(...) returns WebhookVerifyResult(Ok, Timestamp, Reason). Event types: Webhooks.
Development
dotnet test # inside sdk/dotnet (xUnit)
node sdk/scripts/generate-server-sdks.mjs --lang dotnet # at the repo root; regenerates Generated/Java SDK
com.pushizo:pushizo-java — Java 17+, java.net.http and Jackson; generated models, parameter classes, and resources; retries, idempotency, pagination, webhook signature verification.
Ruby SDK
pushizo (RubyGems) — Ruby 3.0+, Net::HTTP; generated models and resource methods, retries, idempotency, Enumerator pagination, webhook signature verification.