Skip to main content
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.

​
Overview

Webhook Implementation

End-to-end guide — configuring endpoints, verifying signatures, handling retries.

Admin API — Webhooks

The three endpoints for configuring webhooks and inspecting delivery logs.

​
Admin API endpoints

MethodPathPurpose
GET/webhooks/configsList every webhook configuration on your organisation.
PUT/webhooks/configsCreate or update a webhook configuration (target URL, enabled event types, secret).
GET/webhooks/logsPaginated delivery log — every attempt, status code, and response body.
Find them in the Admin API → Webhooks 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.
  • Ordering is not guaranteed. Handlers must be order-independent; use the event’s timestamp field for causal ordering within a stream.

​
Event categories

User events

Profile creation, authentication, community joins, opt-in/opt-out.

Action events

Action completion, hint reveal, repeatable action milestones.

Challenge events

Challenge start, completion, recap generation.

Reward events

Reward distribution, claim, redemption, expiry.

Achievement events

Achievement unlock, tier progression, streak milestones.

Referral events

Referral click, conversion, referrer/referee reward distribution.
See the webhook event catalogue 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

1

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 for the full request schema.
2

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).
3

Handle retries and dedupe

Follow the patterns in Webhook Implementation: verify the signature, dedupe on the nonce, reply 2xx on success or 5xx to trigger a retry.

Webhook Implementation Guide

Full handler walkthrough — signatures, retries, debugging.

Admin API — Webhooks

OpenAPI reference for the three config endpoints.

Errors

Error envelope for webhook config mutations.

Authentication

Admin API authentication for /webhooks/* endpoints.