Python

Publish events, sign channel and user auth, validate webhooks, read history, mutate versioned messages, and manage push from Python with the sync or asyncio Sockudo client.

12 min read
View .mdEdit on GitHub

sockudo-http-python is the trusted backend library for calling the Sockudo HTTP API from Python 3.9+. It runs inside your API servers, workers, and web frameworks, signs every request with your app secret, and ships two clients with the same method names: Sockudo for synchronous code and AsyncSockudo for asyncio. It does not hold a WebSocket subscription; use sockudo-python for a realtime consumer.

  • Signed HTTP publishing to one channel, up to 100 channels, or a batch of events
  • Explicit, generated, and automatic idempotency keys, with built-in retries for 5xx and network failures
  • Private, presence, encrypted-channel, and user (signin) authentication signing
  • Webhook signature validation and parsing, including decryption of private-encrypted-* events
  • Channel state, presence members, durable history, presence history, and operator history controls
  • Versioned messages (get, versions, update, delete, append) and annotations (publish, list, delete)
  • Push device registration, channel subscriptions, publish, publish status, and Apple Live Activities
  • Terminate or force-reconnect every connection of a user

Install

Terminal
pip install sockudo-http-python

The package requires Python 3.9 or newer and depends on httpx[http2] (0.27+) and PyNaCl (1.5+). Version 2.2.0 is the current release.

Contributors working inside the Sockudo monorepo can install the package in editable mode with its test tooling:

Terminal
pip install -e "server-sdks/sockudo-http-python[dev]"

The distribution installs two import names: sockudo_http_python and the shorter alias sockudo_http. Both expose the same classes.

Configure the client

sockudo_client.py
import os
from sockudo_http_python import Sockudo, SockudoOptions
sockudo = Sockudo(
os.environ["SOCKUDO_APP_ID"],
os.environ["SOCKUDO_KEY"],
os.environ["SOCKUDO_SECRET"],
# Optional: required only for private-encrypted-* channels.
encryption_master_key_base64=os.environ.get("SOCKUDO_ENCRYPTION_MASTER_KEY"),
options=SockudoOptions(
host=os.environ.get("SOCKUDO_HOST", "127.0.0.1"),
port=int(os.environ.get("SOCKUDO_PORT", "6001")),
use_tls=os.environ.get("SOCKUDO_USE_TLS") == "true",
timeout=4.0,
auto_idempotency=True,
),
)

The constructor takes app_id, key, and secret (all required; an empty value raises SockudoError), an optional encryption_master_key_base64, an optional options, and an optional pre-built client. SockudoOptions holds the transport settings:

OptionTypeDefaultDescription
hoststr"127.0.0.1"Sockudo HTTP host.
portint6001Sockudo HTTP port.
use_tlsboolFalseUse https instead of http. Enable it in production.
timeoutfloat4.0httpx timeout in seconds for each attempt.
max_retriesint3Total attempts per request, including the first. 1 disables retries; 0 sends nothing and returns a network error.
retry_base_delayfloat0.1Base delay in seconds for exponential backoff (0.1, 0.2, …).
auto_idempotencyboolFalseGenerate an idempotency key for publishes and batch items that omit one.
http2boolTrueNegotiate HTTP/2. Falls back to HTTP/1.1 if the h2 package is missing.
verify_tlsbool or strTrueVerify the server certificate; pass a CA bundle path for private PKI.

Constructor arguments outside SockudoOptions:

ArgumentTypeDefaultDescription
encryption_master_key_base64strNoneBase64 key that must decode to exactly 32 bytes; validated at construction.
clienthttpx.Client / httpx.AsyncClientNoneInject your own httpx client. The SDK then does not close it, and timeout, http2, and verify_tls do not apply.

You can also build a client from a Config dataclass, which flattens the same fields, or from a URL. from_url sets host, port (80 or 443 when omitted), and use_tls from the scheme; every other option keeps its default.

alternative_constructors.py
import os
from sockudo_http import Config, Sockudo
from_config = Sockudo(
Config(
app_id=os.environ["SOCKUDO_APP_ID"],
key=os.environ["SOCKUDO_KEY"],
secret=os.environ["SOCKUDO_SECRET"],
host="sockudo.internal",
port=443,
use_tls=True,
)
)
# SOCKUDO_URL=https://app-key:app-secret@sockudo.internal/apps/app-id
from_url = Sockudo.from_url(os.environ["SOCKUDO_URL"])

The asyncio client has the identical constructor and method names; every HTTP method is awaited:

async_client.py
import os
from sockudo_http_python import AsyncSockudo, SockudoOptions
async def publish_order(order_id: str) -> None:
async with AsyncSockudo(
os.environ["SOCKUDO_APP_ID"],
os.environ["SOCKUDO_KEY"],
os.environ["SOCKUDO_SECRET"],
options=SockudoOptions(host="sockudo.internal", port=443, use_tls=True),
) as sockudo:
await sockudo.trigger("orders", "order.created", {"id": order_id})

Use Sockudo in WSGI apps, scripts, and thread-based workers, and AsyncSockudo in ASGI apps and asyncio workers. Do not call the synchronous client from inside an event loop; it blocks the loop for the whole request, including retry backoff. Signing helpers such as authenticate and validate_webhook_signature do no I/O and are plain (non-async) methods on both clients.

Runtime setters exist for set_host, set_port, set_encrypted (TLS), set_auto_idempotency_key, and set_data_marshaller (replace the default compact json.dumps used for event data).

Keep the app secret on the server. It signs every HTTP API call and every channel and user auth response, so anyone holding it can publish to any channel, read history, and impersonate any user. Load it from environment variables or a secret manager, and never ship it to browsers or mobile apps. The same applies to the encryption master key.

Publish an event

publish.py
from sockudo_http_python import TriggerOptions
result = sockudo.trigger(
"orders",
"order.created",
{"id": "ord_123", "total": 4200},
TriggerOptions(idempotency_key="order.created:tenant-42:ord_123:v1"),
)
if not result.ok:
raise RuntimeError(f"publish failed: {result.status.value} {result.status_code}")

trigger returns a Result instead of raising for HTTP failures. It carries status (a Status enum), status_code (the HTTP status, or None for network errors), message (the raw response body), ok, and json() to decode the body. String data is sent as-is; any other value is JSON-encoded.

TriggerOptions accepts:

  • socket_id: exclude one connection from delivery.
  • info: a string or list of attributes, such as ["subscription_count"], to include in the response.
  • idempotency_key: a string, or True to generate a UUID for this call.
  • tags: a dict[str, str] used by Protocol V2 tag filtering.
  • extras: a MessageExtras with headers, ephemeral, idempotency_key, echo, and tags for Protocol V2 message extras.

Pass socket_id when a browser action triggered the publish. The user who clicked “Save” has already updated their own UI optimistically; excluding their connection prevents the server from echoing the same event back and applying it twice. Take the value from the request the client sent you (for example sockudo.connection.socket_id in the JavaScript client).

To deliver to one authenticated user on all of their connections, use send_to_user, which publishes to the user’s #server-to-user-{user_id} channel:

send_to_user.py
sockudo.send_to_user("user-42", "notice", {"body": "Your export is ready"})

Publish to many channels or in a batch

Pass a list of channels to publish the same event to each of them in one request:

multi_channel.py
from sockudo_http_python import TriggerOptions
sockudo.trigger(
["tenant-42:orders", "user-7:orders"],
"order.updated",
{"id": "ord_123", "status": "paid"},
TriggerOptions(socket_id="123.456", idempotency_key="order.paid:ord_123:v3"),
)

Use trigger_batch for different events that can share one HTTP request. Each Event takes a channel, name, and data, plus optional socket_id, info, idempotency_key, extras, and tags:

batch.py
from sockudo_http_python import Event
result = sockudo.trigger_batch(
[
Event("orders", "order.paid", {"id": "ord_123"}, idempotency_key="order.paid:ord_123:v1"),
Event("invoices", "invoice.issued", {"id": "inv_9"}, idempotency_key="invoice.issued:inv_9:v1"),
]
)

The SDK checks two limits before sending: a single trigger accepts at most 100 channels, and a publish to a private-encrypted-* channel cannot target more than one channel. Both raise SockudoError. The batch size is not checked locally. The server enforces its [event_limits] defaults:

LimitDefault
max_channels_at_once100 channels per publish
max_batch_size10 events per batch
max_payload_in_kb100 KB per event payload
max_name_length200 characters per event or channel name

Idempotency and retries

A timeout does not tell you whether Sockudo published the event. The request may have failed before it arrived, or it may have published and the response was lost. Retrying without a key can deliver the event twice; an idempotency key lets the server recognise the retry.

Server semantics:

  • The key can be sent as the body field idempotency_key or the X-Idempotency-Key header; the body field wins when both are present. trigger sends the same key in both.
  • [idempotency] defaults: enabled = true, ttl_seconds = 120, max_key_length = 128. Empty keys are rejected.
  • A duplicate inside the TTL returns the original cached 200 response without publishing again.
  • In a batch, X-Idempotency-Key identifies the whole batch and each item’s idempotency_key identifies only that event; the two key domains do not collide.
  • If the coordination backend is unavailable, the server returns 503 service_unavailable. A concurrent retry while the first attempt is still in flight gets 503 backpressure with Retry-After: 1. Retry both with the same key.

A key names a logical operation, such as order.created:tenant-42:order-123:v1, not an HTTP attempt. Never reuse a key for a different payload.

How this SDK sets keys:

MechanismScopeSurvives an application-level retry?
TriggerOptions(idempotency_key="...") / Event(..., idempotency_key="...")One publish or batch itemYes, if you derive it from business data
idempotency_key=TrueFresh UUID per callNo, only covers the SDK’s own retries
SockudoOptions(auto_idempotency=True)Process-local key per call; batch items get one key eachNo, only covers the SDK’s own retries

trigger_batch sends keys per item only; it does not send a batch-level X-Idempotency-Key header.

Every HTTP call (publishes, reads, and push) retries automatically when the result is a SERVER_ERROR (any 5xx, including 503 backpressure) or a NETWORK_ERROR, up to max_retries total attempts with exponential backoff from retry_base_delay. The retry reuses the same signed URL and body, so the same idempotency key travels with it. The SDK does not read Retry-After and does not retry 429.

Authorize private and presence channels

When a client subscribes to a private- or presence- channel, it asks your backend for a signature. authenticate only produces that signature; it does not decide whether the user may join. Your route must check the session, decide whether this user may access this exact channel, and take presence identity from your own user record, never from the request body.

This FastAPI app uses AsyncSockudo for its HTTP calls and its synchronous authenticate helper for signing. Reading form fields requires python-multipart:

Terminal
pip install fastapi uvicorn python-multipart
app.py
import os
from contextlib import asynccontextmanager
from fastapi import FastAPI, HTTPException, Request, Response
from sockudo_http_python import AsyncSockudo, PresenceUser, SockudoOptions
@asynccontextmanager
async def lifespan(app: FastAPI):
app.state.sockudo = AsyncSockudo(
os.environ["SOCKUDO_APP_ID"],
os.environ["SOCKUDO_KEY"],
os.environ["SOCKUDO_SECRET"],
encryption_master_key_base64=os.environ.get("SOCKUDO_ENCRYPTION_MASTER_KEY"),
options=SockudoOptions(
host=os.environ.get("SOCKUDO_HOST", "127.0.0.1"),
port=int(os.environ.get("SOCKUDO_PORT", "6001")),
use_tls=os.environ.get("SOCKUDO_USE_TLS") == "true",
auto_idempotency=True,
),
)
yield
await app.state.sockudo.close()
app = FastAPI(lifespan=lifespan)
def current_user(request: Request):
"""Return the signed-in user from your session layer, or None."""
...
def can_access(user, channel_name: str) -> bool:
"""Your authorization rule, e.g. tenant membership for this channel."""
...
@app.post("/sockudo/auth")
async def sockudo_auth(request: Request) -> Response:
user = current_user(request)
if user is None:
raise HTTPException(status_code=401)
form = await request.form() # the JS client sends form-encoded fields
socket_id = str(form.get("socket_id", ""))
channel_name = str(form.get("channel_name", ""))
if not socket_id or not channel_name:
raise HTTPException(status_code=400)
if not can_access(user, channel_name):
raise HTTPException(status_code=403)
sockudo: AsyncSockudo = request.app.state.sockudo
if channel_name.startswith("presence-"):
# Identity comes from your session, never from the request body.
body = sockudo.authenticate(
socket_id,
channel_name,
PresenceUser(user.id, {"name": user.display_name}),
)
else:
body = sockudo.authenticate(socket_id, channel_name)
return Response(content=body, media_type="application/json")

authenticate(socket_id, channel, presence_user=None) returns the JSON response body as a string: auth, plus channel_data for presence channels and shared_secret for encrypted channels. PresenceUser(user_id, user_info=None) serializes to the channel_data the presence channel broadcasts to members.

User authentication

User authentication (signin) binds a connection to a user ID so the server can target it with send_to_user, terminate_user_connections, and force_reconnect_user. The user_data must contain an id taken from your session:

app.py
@app.post("/sockudo/user-auth")
async def sockudo_user_auth(request: Request) -> Response:
user = current_user(request)
if user is None:
raise HTTPException(status_code=401)
form = await request.form()
socket_id = str(form.get("socket_id", ""))
if not socket_id:
raise HTTPException(status_code=400)
body = request.app.state.sockudo.authenticate_user(
socket_id, {"id": user.id, "name": user.display_name}
)
return Response(content=body, media_type="application/json")

authenticate_user returns a JSON string with auth and user_data.

Encrypted channels

private-encrypted-* channels carry end-to-end encrypted payloads. Configure encryption_master_key_base64 with a base64 string that decodes to exactly 32 bytes; anything else raises SockudoError when the client is constructed. Generate one with openssl rand -base64 32.

With the key configured, the SDK:

  • adds a per-channel shared_secret (SHA-256 of the channel name and master key) to authenticate responses for encrypted channels, using the same route as above;
  • encrypts trigger and trigger_batch data for encrypted channels with NaCl SecretBox before sending it, so Sockudo never sees plaintext;
  • decrypts encrypted channel events in parse_webhook.

channel_shared_secret(channel) returns the raw 32-byte secret if you need it directly. Keep the master key in a secret manager and never send it to clients; they only ever receive the derived per-channel secret.

Terminate user connections

user_controls.py
# Close every connection for a user, e.g. after a ban or password change.
sockudo.terminate_user_connections("user-42")
# Close every connection with code 4200 so clients reconnect (and re-authenticate).
sockudo.force_reconnect_user("user-42")

Both apply only to connections that completed user authentication and return a Result. They call POST /apps/{app_id}/users/{user_id}/terminate_connections and POST /apps/{app_id}/users/{user_id}/force_reconnect.

Validate webhooks

Sockudo signs each webhook with an HMAC-SHA256 of the exact request body bytes, using your app secret, and sends the app key in X-Pusher-Key and the signature in X-Pusher-Signature. Parsing the JSON and re-serializing it changes whitespace and key order, which breaks the signature, so validate the raw bytes before decoding anything.

app.py
from fastapi import BackgroundTasks
from sockudo_http_python import Validity, Webhook
def handle_webhook(webhook: Webhook) -> None:
for event in webhook.events:
# Deduplicate on your side: delivery can be retried.
if event.name == "channel_occupied":
...
elif event.name == "member_added":
...
@app.post("/sockudo/webhooks")
async def sockudo_webhooks(request: Request, background: BackgroundTasks) -> Response:
raw_body = await request.body() # exact bytes, before any JSON parsing
key = request.headers.get("X-Pusher-Key", "")
signature = request.headers.get("X-Pusher-Signature", "")
sockudo: AsyncSockudo = request.app.state.sockudo
validity = sockudo.validate_webhook_signature(key, signature, raw_body)
if validity is not Validity.VALID:
raise HTTPException(status_code=401)
webhook = sockudo.parse_webhook(key, signature, raw_body)
background.add_task(handle_webhook, webhook)
return Response(status_code=200)

validate_webhook_signature returns a Validity: VALID, INVALID, or SIGNED_WITH_WRONG_KEY (the key header does not match this client’s key). The comparison is constant-time. parse_webhook validates again, raises SockudoError on a bad signature, and returns a Webhook with time_ms and a tuple of WebhookEvent objects (name, channel, event, data, socket_id, user_id, and the full raw payload, so fields added in future server versions are preserved). Encrypted channel events are decrypted when a master key is configured.

Return 200 quickly and do the work asynchronously, as above or through your job queue. Sockudo may retry delivery, so make the handler idempotent. Do not log raw webhook bodies or signatures.

The SDK validates against one key and secret. To rotate credentials, construct a second client with the new key and secret and accept a webhook if either client returns Validity.VALID.

Channel state and history

state.py
from sockudo_http_python import ChannelParams, ChannelsParams
channels = sockudo.list_channels(
ChannelsParams(filter_by_prefix="presence-", info=["user_count"])
)
orders = sockudo.get_channel("orders", ChannelParams(info=["subscription_count"]))
members = sockudo.get_channel_users("presence-lobby")
if channels.ok:
print(channels.json())

Each call returns a Result; decode the response with result.json(). get(path, params=None) is a signed GET helper for any app-scoped endpoint without a dedicated method; a path that does not start with /apps/ is prefixed with /apps/{app_id}. For any other method, signed_uri(method, path, body=None, parameters=None) returns a fully signed URL you can send with your own HTTP client.

History

get_channel_history reads durable history. HistoryParams accepts limit, direction ("newest_first" or "oldest_first"), cursor, start_serial, end_serial, start_time_ms, and end_time_ms. Responses contain items, has_more, and next_cursor. Cursors are opaque: pass next_cursor back unchanged and do not build or edit them.

history.py
from sockudo_http_python import HistoryParams
cursor = None
while True:
page = sockudo.get_channel_history(
"orders", HistoryParams(limit=100, direction="newest_first", cursor=cursor)
)
if not page.ok:
raise RuntimeError(f"history failed: {page.status_code}")
body = page.json()
for item in body["items"]:
process(item)
if not body["has_more"]:
break
cursor = body["next_cursor"]

get_channel_history_state(channel) returns the retention and continuity state of a channel’s stream. Operator controls require a non-empty reason and send the confirmation fields the server expects:

history_ops.py
sockudo.reset_channel_history("orders", reason="corrupted import", requested_by="ops@example.com")
sockudo.purge_channel_history(
"orders", mode="before_time_ms", before_time_ms=1767225600000, reason="retention policy"
)

mode is "all", "before_serial", or "before_time_ms".

Presence history

Presence history records join and leave transitions, separate from current membership.

presence_history.py
from sockudo_http_python import PresenceHistoryParams, PresenceSnapshotParams
transitions = sockudo.get_channel_presence_history(
"presence-lobby", PresenceHistoryParams(limit=50, direction="newest_first")
)
snapshot = sockudo.get_channel_presence_snapshot(
"presence-lobby", PresenceSnapshotParams(at_time_ms=1767225600000)
)

PresenceHistoryParams has the same fields as HistoryParams. PresenceSnapshotParams takes at_serial or at_time_ms to reconstruct membership at a point in time. Also available: get_channel_presence_history_state(channel) and reset_channel_presence_history(channel, reason, requested_by=None).

Versioned messages and annotations

Protocol V2 messages are addressed by message_serial and can be edited, deleted, or appended to after publishing. See Mutable messages for the server model.

versioned_messages.py
from sockudo_http_python import MessageMutation, MessageVersionsParams
sockudo.get_message("orders", "msg:1")
sockudo.get_message_versions("orders", "msg:1", MessageVersionsParams(limit=20))
sockudo.update_message(
"orders",
"msg:1",
MessageMutation(data={"status": "paid"}, description="payment captured"),
)
sockudo.append_message("orders", "msg:1", " more streamed text")
sockudo.delete_message("orders", "msg:1", MessageMutation(description="moderated"))

MessageMutation fields are name, data, extras, clear_fields, client_id, socket_id, description, and metadata; at least one must be set or SockudoError is raised. You may pass a plain dict instead. append_message(channel, message_serial, data, socket_id=None) requires a non-empty string. MessageVersionsParams takes limit, direction, and cursor.

Annotations attach reactions and other summaries to a message:

annotations.py
from sockudo_http_python import AnnotationEventsParams, PublishAnnotationRequest
sockudo.publish_annotation(
"orders",
"msg:1",
PublishAnnotationRequest(
type="reactions:distinct.v1", name="like", client_id="user-42", count=1
),
)
sockudo.list_annotations("orders", "msg:1", AnnotationEventsParams(limit=50))
sockudo.delete_annotation("orders", "msg:1", "ann:1")

PublishAnnotationRequest takes type plus optional name, client_id, socket_id, count, data, and encoding. AnnotationEventsParams takes type, from_serial, limit, and socket_id. Annotation names and client IDs are application data: authorize them in your backend before publishing on a user’s behalf.

Push notifications

The SDK wraps the push API with typed methods; request bodies are plain dicts sent as-is, so their fields follow the server’s camelCase push schema. Admin calls send X-Sockudo-Push-Capability: push-admin. See Push notifications for provider setup and delivery semantics.

push.py
import os
registration = sockudo.activate_device(
{
"appId": os.environ["SOCKUDO_APP_ID"], # replaced by the app in the URL
"id": "android-device-1",
"clientId": "user-42",
"formFactor": "phone",
"platform": "android",
"deviceSecret": "issued-by-server", # replaced on push-admin registration
"timezone": "Europe/Bucharest",
"locale": "en-US",
"push": {
"recipient": {"transportType": "gcm", "registrationToken": fcm_token},
"state": "ACTIVE",
},
}
).json()
# Returned once on first registration (or rotation); hand it to the device.
device_identity_token = registration.get("deviceIdentityToken")
sockudo.upsert_channel_push_subscription(
{
"appId": os.environ["SOCKUDO_APP_ID"],
"channel": "orders",
"deviceId": "android-device-1",
"clientId": "user-42",
"provider": "fcm",
"tokenHash": registration["tokenHash"],
}
)
accepted = sockudo.publish_push(
{
"publishId": "push-order-ord_123-packed",
"recipients": [
{"type": "channel", "channel": "orders"},
{"type": "client", "client_id": "user-42"},
],
"payload": {"title": "Order updated", "body": "Order ord_123 is packed"},
}
)
status = sockudo.get_publish_status("push-order-ord_123-packed")

publish_push, publish_push_batch, and schedule_push always send "sync": false. A successful response is an admission record (publishId, status, expectedRecipients, and rendered provider payloads), not proof of delivery: read get_publish_status(publish_id) later to see provider outcomes. Reuse the same publishId when retrying an ambiguous publish; the server deduplicates on it.

Available push methods:

AreaMethods
Devicesactivate_device(device, rotate_device_identity_token=False), create_device_activation, update_device_registration(device, device_identity_token), get_device_registration, delete_device_registration, list_device_registrations(PushCursorParams), remove_device_registrations_by_client(client_id)
Channel subscriptionsupsert_channel_push_subscription, list_channel_push_subscriptions(PushSubscriptionParams), delete_channel_push_subscriptions(PushSubscriptionParams), list_channel_push_subscription_channels
Publishpublish_push, publish_push_direct, publish_push_batch, schedule_push (requires notBeforeMs), cancel_scheduled_push(publish_id)
Status and feedbackget_publish_status(publish_id), post_push_delivery_status(event)
Credentialslist_push_credentials, put_push_credential(provider, credential)

Device and subscription methods that accept device_identity_token switch to the narrower push-subscribe capability and send X-Sockudo-Device-Identity-Token, so a device can only manage its own registration. PushSubscriptionParams filters by channel or device_id and pages with limit and cursor. Never log provider tokens, device identity tokens, or push credentials.

Apple Live Activities

The SDK exports typed helpers for ActivityKit: ApnsLiveActivityPayload, ApnsLiveActivityEvent (START, UPDATE, END), ApnsLiveActivityPriority, ApnsChannelStoragePolicy (NO_STORAGE, MOST_RECENT), and the recipient builders apns_live_activity_recipient(token) and apns_live_activity_broadcast_recipient(channel_id, storage_policy). Both clients expose create_apns_live_activity_channel, get_apns_live_activity_channel, list_apns_live_activity_channels, and delete_apns_live_activity_channel for iOS 18 broadcast channels. See Apple Live Activities for direct-token and broadcast examples.

Errors and timeouts

The SDK separates two kinds of failure:

  • HTTP and network failures are returned, not raised. Every HTTP method returns a Result whose status is SUCCESS (2xx), AUTHENTICATION_ERROR (401, 403), CLIENT_ERROR (other 4xx, including 413 and 429), SERVER_ERROR (5xx), or NETWORK_ERROR (connection failures and timeouts; status_code is None). result.status.should_retry() is true for the last two.
  • Local validation failures raise SockudoError: missing credentials, an invalid encryption master key, more than 100 channels, a multi-channel encrypted publish, an empty MessageMutation or append, a missing history reason, a scheduled push without notBeforeMs, and invalid or undecryptable webhooks in parse_webhook.
errors.py
from sockudo_http_python import SockudoError, Status, TriggerOptions
try:
result = sockudo.trigger(
"orders",
"order.created",
{"id": "ord_123"},
TriggerOptions(idempotency_key="order.created:tenant-42:ord_123:v1"),
)
except SockudoError:
# A bug in the call itself: fix the input, do not retry.
raise
if result.status is Status.SUCCESS:
pass
elif result.status_code == 429 or result.status.should_retry():
# Built-in retries are exhausted: hand off to your job queue with the SAME key.
schedule_retry(key="order.created:tenant-42:ord_123:v1")
else:
# 400, 401, 403, 413: retrying will not help.
log.error("sockudo publish rejected", extra={"status": result.status_code})

timeout (default 4.0 seconds) bounds each attempt, so the worst case for one call is roughly max_retries * timeout plus backoff. Keep that below your request or job deadline.

What to retry: network errors, 429, and 5xx, always with the same idempotency key. What not to retry: 400, 401, 403, and 413; they indicate a bad request, bad credentials, or an oversized payload. Result.message contains the server’s response body, which is safe to log in truncated form. Never log signed URLs from signed_uri (they contain the signature), the app secret, the encryption master key, raw webhook bodies, or push provider tokens.

Next steps