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

# Overview

> Real-time event notifications from the Nudj platform to your applications

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

<Note>
  **Interactive Testing Available**: You can configure and test webhooks directly from this documentation using our [interactive API playground](/developer/webhooks/testing). No need to write code to get started!
</Note>

## Key Features

<CardGroup cols={2}>
  <Card title="Real-time Notifications" icon="bolt">
    Receive instant notifications when events occur, eliminating the need for polling
  </Card>

  <Card title="Reliable Delivery" icon="shield-check">
    Built-in retry logic with configurable attempts ensures your webhook receives the data
  </Card>

  <Card title="Flexible Configuration" icon="sliders">
    Choose which events to receive and customize HTTP methods and headers
  </Card>

  <Card title="Secure Authentication" icon="lock">
    Custom headers support for secure webhook authentication
  </Card>
</CardGroup>

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

| Field           | Description                                                          | Required |
| --------------- | -------------------------------------------------------------------- | -------- |
| **URL**         | The endpoint where webhook payloads will be sent (HTTPS recommended) | Yes      |
| **Events**      | Specific event types you want to receive notifications for           | Yes      |
| **Max Retries** | Number of delivery attempts on failure (default: 3)                  | No       |
| **Enabled**     | Toggle to enable/disable the webhook without deleting it             | No       |
| **Created At**  | Timestamp showing when the webhook was created                       | Auto     |

<Info>
  All webhooks use the **POST** HTTP method. Your endpoint should accept POST requests with a JSON payload.
</Info>

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

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

**Example Header Configuration:**

```json theme={null}
{
  "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

<Steps>
  <Step title="Configure Your Webhook">
    Use the [interactive API playground](/developer/webhooks/testing) to configure your webhook:

    ```bash theme={null}
    PUT https://{subdomain}.nudj.cx/api/v2/admin/webhooks/configs
    ```
  </Step>

  <Step title="Test with Live Endpoints">
    Try the configuration directly in our [testing guide](/developer/webhooks/testing) with webhook.site or ngrok
  </Step>

  <Step title="Handle Incoming Webhooks">
    Create an endpoint to receive webhook payloads with proper authentication
  </Step>

  <Step title="Verify Delivery">
    Trigger test events and monitor webhook delivery in real-time
  </Step>
</Steps>

## Security Considerations

<Warning>
  Always validate webhook requests in production to ensure they're coming from Nudj
</Warning>

* **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](/developer/webhooks/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

<CardGroup cols={2}>
  <Card title="Test Webhooks" icon="vial" href="/developer/webhooks/testing">
    Configure and test webhooks interactively
  </Card>

  <Card title="Browse Events" icon="list" href="/developer/webhooks/event-catalog">
    See all available events with examples
  </Card>

  <Card title="Code Examples" icon="code" href="/developer/webhooks/recipes">
    Ready-to-use integrations for popular platforms
  </Card>

  <Card title="Build Your Handler" icon="hammer" href="/developer/webhooks/implementation">
    Step-by-step implementation guide
  </Card>
</CardGroup>

## Need Help?

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