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

# Webhooks

> Outbound webhook events and delivery model

Nudj emits outbound webhooks to your customer systems when tracked events fire in the platform. This page is the API-reference overview — for the full event catalogue, payload shapes, signing, retry semantics, and step-by-step implementation, see the [Webhook Implementation Guide](/developer/webhooks/implementation).

## Overview

<CardGroup cols={2}>
  <Card title="Webhook Implementation" icon="code" href="/developer/webhooks/implementation">
    End-to-end guide — configuring endpoints, verifying signatures, handling retries.
  </Card>

  <Card title="Admin API — Webhooks" icon="list" href="/api-reference/admin/get-webhooks-configs">
    The three endpoints for configuring webhooks and inspecting delivery logs.
  </Card>
</CardGroup>

## Admin API endpoints

| Method | Path                | Purpose                                                                             |
| ------ | ------------------- | ----------------------------------------------------------------------------------- |
| `GET`  | `/webhooks/configs` | List every webhook configuration on your organisation.                              |
| `PUT`  | `/webhooks/configs` | Create or update a webhook configuration (target URL, enabled event types, secret). |
| `GET`  | `/webhooks/logs`    | Paginated delivery log — every attempt, status code, and response body.             |

Find them in the [Admin API → Webhooks](/api-reference/admin/get-webhooks-configs) group in the sidebar.

## Delivery model

* **At-least-once delivery.** Every webhook carries a deterministic nonce (event id) so your handler can idempotently dedupe.
* **Retries with exponential backoff.** Failed deliveries retry on a QStash-backed queue — HTTP `5xx` and connection errors trigger retries, `4xx` responses do not.
* **Signed payloads.** Every delivery is signed with your endpoint's shared secret. Verify the signature before processing — see [Webhook Implementation](/developer/webhooks/implementation).
* **Ordering is not guaranteed.** Handlers must be order-independent; use the event's timestamp field for causal ordering within a stream.

## Event categories

<CardGroup cols={2}>
  <Card title="User events" icon="user">
    Profile creation, authentication, community joins, opt-in/opt-out.
  </Card>

  <Card title="Action events" icon="list-check">
    Action completion, hint reveal, repeatable action milestones.
  </Card>

  <Card title="Challenge events" icon="trophy">
    Challenge start, completion, recap generation.
  </Card>

  <Card title="Reward events" icon="gift">
    Reward distribution, claim, redemption, expiry.
  </Card>

  <Card title="Achievement events" icon="medal">
    Achievement unlock, tier progression, streak milestones.
  </Card>

  <Card title="Referral events" icon="share-nodes">
    Referral click, conversion, referrer/referee reward distribution.
  </Card>
</CardGroup>

See the [webhook event catalogue](/developer/webhooks/event-catalog) for every event type and payload schema.

## Idempotency

Every webhook includes a unique event id in the payload. The recommended pattern:

1. Store every processed event id in a short-TTL cache (e.g. Redis, 24h).
2. On receipt, check the cache — if already processed, return `200` without doing any work.
3. Otherwise, process the event, then write the id to the cache.

This is safe against both duplicate deliveries from retries and any future changes to the delivery queue.

## Configuration flow

<Steps>
  <Step title="Register an endpoint">
    Call `PUT /webhooks/configs` with your receiving URL, the event types you care about, and optionally a secret for HMAC signing. See the [Admin API reference](/api-reference/admin/put-webhooks-configs) for the full request schema.
  </Step>

  <Step title="Verify delivery">
    Trigger an action in the admin dashboard (or via the API) and inspect `GET /webhooks/logs` — every attempt is logged with the outgoing payload, target URL, response status code, and error body (if any).
  </Step>

  <Step title="Handle retries and dedupe">
    Follow the patterns in [Webhook Implementation](/developer/webhooks/implementation): verify the signature, dedupe on the nonce, reply `2xx` on success or `5xx` to trigger a retry.
  </Step>
</Steps>

## Related

<CardGroup cols={2}>
  <Card title="Webhook Implementation Guide" icon="code" href="/developer/webhooks/implementation">
    Full handler walkthrough — signatures, retries, debugging.
  </Card>

  <Card title="Admin API — Webhooks" icon="list" href="/api-reference/admin/get-webhooks-configs">
    OpenAPI reference for the three config endpoints.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/api-reference/errors">
    Error envelope for webhook config mutations.
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Admin API authentication for `/webhooks/*` endpoints.
  </Card>
</CardGroup>