PushizoDocs
SDK guides

.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 Pushizo

Usage

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

PushizoOptionsDefaultDescription
ApiKey—hs_live_… API key (Bearer)
AppId—App used when a call doesn't pass RequestOptions.AppId
BaseUrlhttps://api.pushizo.comAPI URL
Timeout30 sTimeout per attempt
MaxRetries3Maximum retries (policy)
AutoIdempotencyKeytrueAutomatic UUID on calls that support Idempotency-Key
HttpClientnew instanceCustom 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, NetworkException

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

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 (HttpRequestError.NameResolutionError/ConnectionError, SocketError.ConnectionRefused/HostNotFound/HostUnreachable)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.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/

On this page