Webhook Events Catalog

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.

Event	When it fires	Typical consumer
`reward.earned`	User completes a challenge or hits a qualification condition and a reward is credited	Loyalty wallet sync
`reward.delivered`	Reward successfully delivered to the user or the downstream system	Confirmation email
`reward.delivery_failed`	Delivery failed after retries	Alerting / support tooling
`reward.redeemed`	A redeemable reward (discount code, checkout link, etc.) has been consumed	Inventory update
`reward.expired`	Time-limited reward expired without redemption	Analytics

Engagement events

Event	When it fires
`challenge.started`	User joins / starts a challenge
`challenge.completed`	User completes a challenge
`action.completed`	User completes a single action (quiz, question, submission, etc.)
`achievement.earned`	User hits an achievement (including tiered achievements)
`points.awarded`	Points transaction applied (positive or negative)

Referral events

The referral distribution events fire when a referee qualifies:

Event	When it fires
`referral.referrer_credited`	Referrer’s reward distributed
`referral.referee_credited`	Referee’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

Getting Started

Authentication

Embedding

Shopify

Rewards & Webhooks

Customer Data

Privacy & Compliance

Reward events

Engagement events

Referral events

Shopify-driven events (inbound bridge)

Payload conventions

Signing and retries

Next steps

Webhook implementation

Delivery logs

​Reward events

​Engagement events

​Referral events

​Shopify-driven events (inbound bridge)

​Payload conventions

​Signing and retries

​Next steps

Webhook implementation

Delivery logs

Reward events

Engagement events

Referral events

Shopify-driven events (inbound bridge)

Payload conventions

Signing and retries

Next steps