Skip to main content
Nudj emits HTTP POST webhooks for domain events your downstream systems care about — reward earned, reward delivered, subscription updates, Shopify-driven achievement triggers, and more. This page covers the protocol — signatures, retries, and endpoint implementation. For the full list of emitted events, see the events catalog. To debug a delivery, see the delivery logs page.

Configuring a webhook

Webhook configurations are managed via the Admin API under /api/v2/admin/webhooks/configs. Each config specifies:
  • url — your endpoint. Must be HTTPS in production.
  • events — list of event types the config subscribes to. See Webhook Events Catalog.
  • secret — used to compute the HMAC signature on each delivery.
  • active — pause or resume deliveries without deleting the config.
Example config:

Request shape

Every delivery is an HTTP POST with a JSON body:
Headers:
  • Content-Type: application/json
  • X-Nudj-Signature: sha256=<hex> — HMAC-SHA256 of the raw body, signed with your configured secret.
  • X-Nudj-Event — convenience header mirroring event in the payload.
  • X-Nudj-Delivery-Id — unique per delivery attempt, stable across retries. Use this to idempotency-key your processing.

Signature verification

Compute HMAC-SHA256 over the raw request body using your configured secret, then compare against the value after sha256= in the X-Nudj-Signature header. Use a timing-safe comparison.
Verify the signature against the raw request body before parsing as JSON. Re-serialising the parsed body will produce a different byte sequence and the HMAC will never match.

Response and retry semantics

  • Respond with 2xx within 30 seconds to acknowledge receipt.
  • Any 5xx response, connection failure, or timeout triggers a retry.
  • Retries use exponential backoff.
  • A delivery that fails every retry attempt is marked failed in the delivery logs.

Idempotency

Process events idempotently. The X-Nudj-Delivery-Id header is stable across retries of the same delivery attempt, and the payload’s data.*.id fields identify the underlying entity. Storing processed delivery IDs in your side lets you no-op duplicates safely.

Local development

Use a tunnel such as ngrok or cloudflared to expose your local endpoint:

Webhook events catalog

Reference of every event type Nudj emits, with example payloads.

Webhook delivery logs

Inspect retry state, bodies, and failures via the Admin API.

Reward integration

Higher-level integration patterns for getting rewards to downstream systems.
Last reviewed: 2026-04