> ## 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.

# Webhook Events Catalog

> Reference of event types Nudj emits via outbound webhooks, grouped by domain.

This page enumerates the outbound webhook events Nudj publishes to configured endpoints. For delivery mechanics (signing, retries, example endpoint code) see [Webhook Implementation](/enterprise/webhook-rewards). For delivery history and debugging, see [Webhook Delivery Logs](/enterprise/webhook-logs).

<Info>
  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.
</Info>

## 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](/enterprise/shopify/webhooks) 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:

```json theme={null}
{
  "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](/enterprise/webhook-rewards). 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

<CardGroup cols={2}>
  <Card title="Webhook implementation" icon="webhook" href="/enterprise/webhook-rewards">
    Sign verification, retries, sample endpoints.
  </Card>

  <Card title="Delivery logs" icon="clock-rotate-left" href="/enterprise/webhook-logs">
    Inspect delivery history and retry state.
  </Card>
</CardGroup>

> Last reviewed: 2026-04 · Related PRs: #1780