Skip to main content

​
What are Webhooks?

Webhooks allow your application to receive real-time notifications when specific events occur within the Nudj platform. Instead of constantly polling our API for updates, webhooks push data to your application immediately when something happens. When an event occurs (such as a user completing a challenge or earning a reward), Nudj sends an HTTP request to your configured webhook endpoint with event details.
Interactive Testing Available: You can configure and test webhooks directly from this documentation using our interactive API playground. No need to write code to get started!

​
Key Features

Real-time Notifications

Receive instant notifications when events occur, eliminating the need for polling

Reliable Delivery

Built-in retry logic with configurable attempts ensures your webhook receives the data

Flexible Configuration

Choose which events to receive and customize HTTP methods and headers

Secure Authentication

Custom headers support for secure webhook authentication

​
How Webhooks Work

  1. Event Occurs: A user action or system event triggers within your Nudj community
  2. Webhook Triggered: Nudj identifies configured webhooks for the event type
  3. HTTP Request Sent: A POST request is sent to your webhook URL with a JSON payload
  4. Response Processed: Your application processes the webhook data
  5. Retry if Needed: If delivery fails, Nudj automatically retries based on your configuration

​
Webhook Configuration

Webhooks are configured at the organisation level, meaning all communities within an organisation share the same webhook configuration. You can manage webhooks from the Admin Panel under Settings → Organisation → Webhooks.

​
Basic Configuration

FieldDescriptionRequired
URLThe endpoint where webhook payloads will be sent (HTTPS recommended)Yes
EventsSpecific event types you want to receive notifications forYes
Max RetriesNumber of delivery attempts on failure (default: 3)No
EnabledToggle to enable/disable the webhook without deleting itNo
Created AtTimestamp showing when the webhook was createdAuto
All webhooks use the POST HTTP method. Your endpoint should accept POST requests with a JSON payload.

​
Custom Headers (Advanced)

You can configure custom HTTP headers for webhooks that require authentication. This is useful when your webhook endpoint requires:
  • API Keys: x-api-key: YOUR_SECRET_KEY
  • Bearer Tokens: Authorization: Bearer YOUR_TOKEN
  • Custom Authentication: Any header your endpoint expects
Headers are configured in the Advanced Settings section when creating a webhook. Each header is a key-value pair that will be sent with every webhook request.
Example Header Configuration: 
{
  "x-api-key": "7AFDD775334D43A2937D461997408414",
  "Content-Type": "application/json"
}

​
Event Filtering

You can configure webhooks to receive notifications for specific event categories:
  • User Activity: Challenge completions, action participations, social interactions
  • Achievements & Rewards: Achievement completions, reward claims and redemptions
  • Content Engagement: Post likes, comments, community visits
  • User Profile Changes: Profile updates, variable captures
  • System Events: Custom events, referral usage

​
Quick Start

1

Configure Your Webhook

Use the interactive API playground to configure your webhook:
PUT https://{subdomain}.nudj.cx/api/v2/admin/webhooks/configs
2

Test with Live Endpoints

Try the configuration directly in our testing guide with webhook.site or ngrok
3

Handle Incoming Webhooks

Create an endpoint to receive webhook payloads with proper authentication
4

Verify Delivery

Trigger test events and monitor webhook delivery in real-time

​
Security Considerations

Always validate webhook requests in production to ensure they’re coming from Nudj
  • Custom Headers: Use authentication headers to verify request authenticity
  • HTTPS Only: Always use HTTPS endpoints for webhook URLs
  • IP Allowlisting: Consider restricting webhook traffic to known Nudj IP ranges
  • Request Validation: Verify the request structure matches expected webhook format

​
How Webhooks Are Delivered

​
What You Need to Know

  • Success: Return any 2xx status code (200, 201, 204, etc.)
  • Retries: Failed webhooks retry up to 3 times with 5-second delays
  • Timeout: Respond within 5 seconds to avoid timeouts
  • Order: Events are delivered in the order they occur

​
Supported Events

Nudj supports webhook notifications for key platform events. See our Event Catalog for the complete list of available events and their payload structures.

​
Event Categories

  • Challenge Events: challenge.started, challenge.completed
  • Achievement Events: achievement.completion
  • Reward Events: reward.claim, reward.redemption, reward.distribution
  • User Events: Profile updates, community joins
  • Social Events: Post interactions, comments, shares
  • Custom Events: Organization-specific custom events

​
Where to Start

Test Webhooks

Configure and test webhooks interactively

Browse Events

See all available events with examples

Code Examples

Ready-to-use integrations for popular platforms

Build Your Handler

Step-by-step implementation guide

​
Need Help?

If you need assistance setting up webhooks or have questions about specific events, please contact our support team at support@nudj.cx.