Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nudj.cx/llms.txt

Use this file to discover all available pages before exploring further.

This page enumerates the outbound webhook events Nudj publishes to configured endpoints. For delivery mechanics (signing, retries, example endpoint code) see Webhook Implementation. For delivery history and debugging, see Webhook Delivery Logs.
Subscribe to specific events per webhook config — delivering every event to every endpoint burns your endpoint and inflates the delivery logs. The per-config events field filters the stream.

​
Reward events

The core events most integrations subscribe to.
EventWhen it firesTypical consumer
reward.earnedUser completes a challenge or hits a qualification condition and a reward is creditedLoyalty wallet sync
reward.deliveredReward successfully delivered to the user or the downstream systemConfirmation email
reward.delivery_failedDelivery failed after retriesAlerting / support tooling
reward.redeemedA redeemable reward (discount code, checkout link, etc.) has been consumedInventory update
reward.expiredTime-limited reward expired without redemptionAnalytics

​
Engagement events

EventWhen it fires
challenge.startedUser joins / starts a challenge
challenge.completedUser completes a challenge
action.completedUser completes a single action (quiz, question, submission, etc.)
achievement.earnedUser hits an achievement (including tiered achievements)
points.awardedPoints transaction applied (positive or negative)

​
Referral events

The referral distribution events fire when a referee qualifies:
EventWhen it fires
referral.referrer_creditedReferrer’s reward distributed
referral.referee_creditedReferee’s welcome reward distributed

​
Shopify-driven events (inbound bridge)

PR #1780 subscribed Nudj to 16 Shopify webhook topics that drive internal events. These are consumed inside Nudj’s handle-event.ts pipeline and typically trigger achievement.earned / points.awarded outbound webhooks rather than being re-emitted verbatim. See Shopify Webhook Integration for the topic list. If a Shopify topic does pass through verbatim, the outbound event name is prefixed shopify. (e.g. shopify.orders_create) and the payload includes both the Nudj user context and the raw Shopify event body.

​
Payload conventions

Every payload is wrapped in a stable envelope: 
{
  "event": "reward.earned",
  "timestamp": "2026-04-17T14:30:00.000Z",
  "deliveryId": "del_2f3a...",
  "data": {
    // event-specific body
  }
}
  • deliveryId matches the X-Nudj-Delivery-Id header. Use it as your idempotency key.
  • Entity IDs inside data.* are stable across the lifecycle of the entity.
  • Timestamps are ISO-8601 UTC.

​
Signing and retries

Every event is signed with HMAC-SHA256 per Webhook Implementation. Delivery retries with exponential backoff on 5xx, timeouts, and connection errors. Terminal 4xx responses (other than the documented 410 Gone — see Shopify-specific webhooks page) are not retried.

​
Next steps

Webhook implementation

Sign verification, retries, sample endpoints.

Delivery logs

Inspect delivery history and retry state.
Last reviewed: 2026-04 · Related PRs: #1780