Skip to main content
Interactive API Playground: Click the cards below to open the API playground where you can directly test and configure your webhooks with your API credentials.

​
Interactive Webhook Configuration

Configure and test your webhooks using the interactive API playground:

Get Configuration

View your current webhook settings

Update Configuration

Configure webhook events and URL

​
Get Current Configuration

Retrieve your current webhook configuration to see what events you’re subscribed to.

Try It Now

Click here to get your current webhook configuration using the interactive API playground

​
Example Response

{
  "configs": [
    {
      "events": [
        "challenge-completion",
        "reward-distribution",
        "achievement-completion"
      ],
      "url": "https://your-webhook-endpoint.com/webhooks/nudj",
      "httpMethod": "POST",
      "isEnabled": true,
      "maxRetries": 3,
      "headers": {
        "X-API-Key": "your-secret-key"
      }
    }
  ]
}

​
Configure Webhooks

Update your webhook configuration to subscribe to specific events and set your endpoint URL.

Try It Now

Click here to configure your webhooks using the interactive API playground

​
Configuration Examples

Start with essential events for most integrations:
{
  "configs": [
    {
      "events": [
        "challenge-completion",
        "reward-distribution"
      ],
      "url": "https://your-app.com/webhooks/nudj",
      "httpMethod": "POST",
      "isEnabled": true,
      "maxRetries": 3,
      "headers": {
        "X-API-Key": "your-webhook-secret"
      }
    }
  ]
}

​
Testing Your Webhook

Follow these steps to test your webhook configuration:

​
Step 1: Set Up a Test Endpoint

  1. Visit webhook.site
  2. Copy your unique URL
  3. Use it as your webhook URL in the configuration
  4. Monitor incoming requests in real-time

​
Step 2: Configure Your Webhook

Use the PUT endpoint to set your test webhook URL: 
curl -X PUT https://{subdomain}.nudj.cx/api/v2/admin/webhooks/configs \
  -H "x-api-token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "configs": [{
      "events": ["challenge-completion"],
      "url": "https://webhook.site/YOUR-UNIQUE-URL",
      "httpMethod": "POST",
      "isEnabled": true,
      "maxRetries": 1,
      "headers": {
        "X-API-Key": "test-secret"
      }
    }]
  }'

​
Step 3: Trigger Test Events

Perform actions in your Nudj community to trigger webhook events:
ActionTriggered EventExpected Payload
Complete a challengechallenge-completionContains challengeId, userId
Earn rewardsreward-distributionContains points, XP, rewards
Unlock achievementachievement-completionContains achievement details
Purchase from shopshop-purchaseContains purchase details
Like a postpost-likeContains postId

​
Step 4: Verify Delivery

Check your test endpoint to confirm webhook delivery:
What to Look For:
  • HTTP method matches configuration (POST/PUT/GET)
  • Custom headers are present
  • Event payload structure is correct
  • Response status is 2xx

​
Testing Checklist

Use this checklist to ensure your webhook integration is working correctly:
1

Configure Test Endpoint

Set up webhook.site, ngrok, or RequestBin endpoint
2

Update Configuration

Use PUT endpoint to set your webhook URL and events
3

Verify Configuration

Use GET endpoint to confirm settings are saved
4

Trigger Test Event

Complete a challenge or perform another action
5

Check Delivery

Verify webhook received at test endpoint
6

Validate Payload

Confirm event structure matches documentation
7

Test Error Handling

Return non-2xx status to test retry logic
8

Switch to Production

Update URL to production endpoint

​
Common Test Scenarios

​
Testing Retry Logic

To test the retry mechanism:
  1. Configure webhook with maxRetries: 3
  2. Have your endpoint return 500 status
  3. Observe 3 delivery attempts with 5-second delays
  4. After 3 failures, webhook marked as failed

​
Testing Authentication

Verify your authentication headers: 
app.post('/webhooks/test', (req, res) => {
  const apiKey = req.headers['x-api-key'];
  
  if (apiKey !== 'expected-secret') {
    console.log('Auth failed:', apiKey);
    return res.status(401).json({ error: 'Unauthorized' });
  }
  
  console.log('Auth successful');
  res.status(200).json({ success: true });
});

​
Testing Idempotency

Ensure duplicate events are handled: 
const processedEvents = new Set();

app.post('/webhooks/test', (req, res) => {
  const eventId = req.body.id;
  
  if (processedEvents.has(eventId)) {
    console.log('Duplicate event:', eventId);
    return res.status(200).json({ duplicate: true });
  }
  
  processedEvents.add(eventId);
  console.log('New event:', eventId);
  res.status(200).json({ success: true });
});

​
Monitoring Webhook Health

​
Key Metrics to Track

  • Delivery Success Rate: Should be > 99%
  • Average Response Time: Should be < 1 second
  • Retry Rate: Should be < 1%
  • Failed Deliveries: Should be investigated immediately

​
Health Check Endpoint

Implement a health check for your webhook: 
app.get('/webhooks/health', (req, res) => {
  res.status(200).json({
    status: 'healthy',
    uptime: process.uptime(),
    memory: process.memoryUsage(),
    lastWebhook: lastWebhookTime,
    totalProcessed: webhookCount
  });
});

​
Troubleshooting Test Issues

  • Verify webhook is enabled (isEnabled: true)
  • Check URL is publicly accessible (not localhost)
  • Confirm events are in the subscription list
  • Ensure organization has active events
  • Verify custom headers match exactly
  • Check for case sensitivity in header names
  • Ensure HTTPS is used (not HTTP)
  • Compare received payload with documentation
  • Check JSON parsing for large payloads
  • Verify character encoding (UTF-8)
  • Check for timeout issues (> 5 seconds)
  • Monitor server resource usage
  • Review network connectivity
  • Check for rate limiting