PushizoDocs
API reference

Idempotency

The Idempotency-Key header and idempotency_key field, 24-hour retention, same/different body behavior, the in-progress request lease, which operations support it, and automatic keys in the SDKs.

To retry safely after a network error or timeout, use an idempotency key on write operations: a request repeated with the same key does not create a second resource; the original response is returned.

Usage

POST /v1/notifications HTTP/1.1
Authorization: Bearer hs_live_…
Idempotency-Key: order-1001
Content-Type: application/json

{ "app_id": "app_…", "target": { "include_external_ids": ["user_42"] }, "contents": { "tr": "…" } }
  • The header is the preferred way; for compatibility with legacy providers, the idempotency_key field in the body is also accepted. If both are given and differ, you get 400 HS_VALIDATION_ERROR.
  • A key is at most 255 characters and is unique per app; use a business-meaningful value such as an order number, or a UUID.
  • Which operations support it is shown in the reference parameter table as the Idempotency-Key header: most notably POST /v1/notifications and POST /v1/apps/{app_id}/users (upsert).

Behavior

SituationResponse
New keyThe request is processed; the response and a body digest (SHA-256) are stored for 24 hours
Same key + same body (within 24 hours)The stored response is returned as-is (same id, same status code); no new message is created
Same key + different body409 HS_IDEMPOTENCY_CONFLICT
Same key, first request still processing409 HS_IDEMPOTENCY_IN_PROGRESS — retry the same request shortly
Process crashed during the first requestThe record is released after a 2-minute lease; a retry takes over
After 24 hoursThe key can be reused (new operation)

Concurrent requests with the same key are serialized at the database level (single winner); the loser of the race receives 409 HS_IDEMPOTENCY_IN_PROGRESS.

In the SDKs

With autoIdempotencyKey (on by default), the server SDKs generate a UUID automatically for idempotent operations when you don't pass a key, and use the same key on retries; so a retry after 429/5xx never produces a duplicate message. Explicit key: Node hs.notifications.create(body, { idempotencyKey }) or idempotency_key in the body; Python/Ruby idempotency_key=; Go pushizo.WithIdempotencyKey("…"); Java RequestOptions.builder().idempotencyKey("…"); .NET new RequestOptions { IdempotencyKey = "…" }; PHP create([...,'idempotency_key' => '…']).

Other write operations

For operations that don't support idempotency keys, rely on natural idempotency: user/alias/subscription write endpoints have external_id/token-based upsert behavior; campaign state transitions (send, pause, cancel) return the current state or 409 HS_CONFLICT when repeated; on the webhook receiver side, deduplicate using Pushizo-Event-Id.

On this page