SDKs de Webhooks
Estado: publicado. Python, TypeScript y Go están en sus registros públicos en la versión 0.8.0. Java y PHP están escritos y probados, pero todavía no se han publicado — consulta el estado actual.
Clientes oficiales de NimbusNexus Webhooks. Todos cubren las mismas cuatro tareas, así que un equipo que usa dos lenguajes obtiene el mismo comportamiento en ambos. Elige un lenguaje en la parte superior de la página y todos los ejemplos lo seguirán; Configura un SDK es la versión corta de la instalación, la autenticación y una primera llamada.
Estos son los clientes de Webhooks. Los SDKs de Infraestructura (VMs, almacenamiento, red) todavía no están disponibles; llama a esa API por REST. Los ejemplos de Go importan el paquete con el alias
nnwhpara que se vea de dónde viene.
La pieza más valiosa es verify. La comprobación de firmas es crítica para la seguridad, es fácil implementarla con errores sutiles y esos errores pasan todos los tests funcionales — los SDKs implementan el contrato completo, incluidas la comparación en tiempo constante y la ventana de replay.
Instalación
pip install nn-webhooks-sdkNo REST example here; showing Python.
Verifica un webhook entrante
Para quien recibe webhooks. Pasa los bytes del cuerpo en bruto — nunca un objeto vuelto a serializar.
from nn_webhooks import verify
ok = verify(
secret=ENDPOINT_SIGNING_SECRET,
raw_body=request.body,
signature=request.headers["X-Webhook-Signature"],
timestamp=request.headers["X-Webhook-Timestamp"],
)
if not ok:
return Response(status_code=400) # forged, tampered, or outside the 300s windowNo REST example here; showing Python.
Pasa siempre el timestamp. Si lo omites, la firma se calcula solo sobre el cuerpo, lo que nunca coincide con lo que enviamos — así que la verificación falla para todo, no solo para los replays. Si verify devuelve false para entregas que crees auténticas, lo primero que debes comprobar es si falta el timestamp.
Publica un evento
Para productores. Los fallos transitorios — errores de conexión, 429, 5xx — se reintentan con backoff, y un 429 respeta Retry-After. Los demás 4xx lanzan una excepción.
La clave se emite en tu consola de la cuenta de NimbusNexus — consulta Cómo obtener acceso. Una clave whsk_… de antes del cambio se rechaza como credencial no reconocida, y ningún SDK comprueba el formato de la clave, así que el fallo aparece como un 403 invalid_credential de la API y no como un error al construir el cliente.
from nn_webhooks import Client, WebhooksAPIError
with Client("https://webhooks.nimbusnexus.net", api_key=WEBHOOKS_API_KEY) as wh:
try:
event = wh.publish(
"order.created",
{"order_id": "ord_123", "total": 4200},
idempotency_key="order-123", # makes the publish safe to retry
)
print(event.event_uid, event.deliveries_created)
except WebhooksAPIError as e:
print(e.status_code, e.code, e.message)No REST example here; showing Python.
Buffer duradero
publish() es síncrono — si la API no está accesible, lanza una excepción y el evento se pierde. El outbox de escritura previa desacopla ambas cosas: enqueue() guarda en un almacén y vuelve de inmediato sin ninguna llamada de red, y drain() envía lo pendiente más tarde.
from nn_webhooks import Client, SQLiteStore
store = SQLiteStore("outbox.db")
# Construct for the process lifetime — NOT in a `with` block. Closing the client stops the
# drainer, so a `with` that exits immediately would shut down the thread you just started.
wh = Client("https://webhooks.nimbusnexus.net", api_key=WEBHOOKS_API_KEY, store=store)
wh.start_drainer(interval_seconds=5) # ships in the background
wh.enqueue("order.created", {"order_id": "ord_123"}) # returns at once, no network
...
wh.close() # at shutdown; also stops the drainerCada envío lleva Idempotency-Key = record.id, así que volver a vaciar tras una caída nunca publica dos veces. Un registro que sigue fallando se reintenta con backoff exponencial con tope hasta max_attempts (10 por defecto), y después se marca como muerto y se pasa a un callback on_dead opcional.
| Almacén | Duradero | Dependencia adicional |
|---|---|---|
MemoryStore | No — en el proceso | ninguna |
FileStore(dir) | Sí | ninguna |
SQLiteStore(path) | Sí, transaccional | ninguna |
RedisStore(url) | Sí | pip install 'nn-webhooks-sdk[redis]' |
PostgresStore(dsn) | Sí | pip install 'nn-webhooks-sdk[postgres]' |
Ningún almacén necesita una dependencia más allá del propio SDK — la única dependencia de ejecución de Python es httpx — y los almacenes de Redis y Postgres importan su controlador de forma diferida, solo cuando se construyen.
Gestiona endpoints
El mismo cliente envuelve el plano de control, con una clave de alcance admin:
ep = wh.create_endpoint(
"https://your-app.example/webhooks",
subscriptions=[{"match_kind": "prefix", "pattern": "order."}],
)
endpoint_id, signing_secret = ep["id"], ep["secret"] # secret returned once
wh.replace_subscriptions(endpoint_id, [ # replaces the whole set
{"match_kind": "exact", "pattern": "order.paid"},
])
wh.rotate_endpoint_secret(endpoint_id)
wh.enable_endpoint(endpoint_id) # recover an auto-disabled endpoint
for d in wh.list_deliveries(status="dead")["items"]: # drain the dead-letter queue
wh.redeliver(d["id"])Los métodos de listado devuelven {"items": [...], "next_offset": int | None}; los de borrado no devuelven nada con un 204.
update_endpoint no puede cambiar las suscripciones, porque webhookd las ignora en un PATCH: replace_subscriptions (replaceSubscriptions en TypeScript, ReplaceSubscriptions en Go) fija la lista completa de una vez, y una lista vacía da de baja el endpoint de todo.
Los métodos de gestión de claves — create_api_key/revoke_api_key en Python, createApiKey/revokeApiKey en TypeScript, Java y PHP, CreateAPIKey/RevokeAPIKey en Go — siguen en el cliente, pero las rutas /v1/api-keys a las que llaman se eliminaron, así que llamar a uno ahora falla con un 404; emite las claves en la consola de la cuenta.
Cómo apuntar a un proyecto
Un proyecto se identifica por su id (prj_3f9a…) — no hay slug ni nombre corto. Deja project_id sin definir para apuntar al proyecto por defecto del workspace, que es lo que siempre quiere un workspace con un solo proyecto:
wh.publish("order.created", {...}) # default project
wh.publish("order.created", {...}, project_id="prj_3f9a…") # a specific oneSolo el servidor puede resolver "el proyecto por defecto", así que omitir el campo es la forma de pedirlo. Pasar una cadena inventada — "default", o el nombre visible de un proyecto — da un 404. El id real aparece en cualquier respuesta, o se obtiene con GET /v1/projects.
Cómo mantenemos fieles los SDKs
Todos los clientes implementan un único contrato de firma: HMAC-SHA256(secret, "<timestamp>." + raw_body), enviado como X-Webhook-Signature: sha256=<hex> con una ventana de 300 segundos. Están atados a él mediante un conjunto compartido de vectores de prueba generado por el propio firmador del servidor, así que ningún cliente puede desviarse del servidor ni de los demás — tampoco en CI, donde el paquete del servidor no está instalado.
Estado actual
| Lenguaje | Paquete | Estado |
|---|---|---|
| Python | nn-webhooks-sdk | Publicado — PyPI, 0.8.0 |
| TypeScript | @nimbusnexus/webhooks-sdk | Publicado — npm, 0.8.0 |
| Go | github.com/NimbusNexus/webhooks-go | Publicado — GitHub, v0.8.0 |
| Java | net.nimbusnexus:webhooks-sdk | Escrito y probado; todavía no está en Maven Central |
| PHP | nimbusnexus/webhooks-sdk | Escrito y probado; todavía no está en Packagist |
Hasta que se publiquen Java y PHP, llama directamente a la API REST — la página de firmas tiene todo lo necesario para verificar entregas en cualquier lenguaje, y son unas veinte líneas.
Próximos pasos
- CLI — las mismas operaciones desde un shell.
- Verificación de firmas — lo que implementa
verify. - Inicio rápido — el flujo que envuelven estos clientes.
- Idempotencia — el patrón de toda la plataforma que hay detrás de
idempotency_key.