Testing & Configuration

Interactive webhook configuration and testing guide

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

Basic Setup

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"
      }
    }
  ]
}

Full Integration

Subscribe to all available webhook events:

{
  "configs": [
    {
      "events": [
        "achievement-completion",
        "auth.email",
        "challenge-completion",
        "challenge-started",
        "organisation.invite-admin-user",
        "post-comment",
        "post-like",
        "reward-claim",
        "reward-distribution",
        "reward-redemption",
        "shop-purchase",
        "streak-extended"
      ],
      "url": "https://your-app.com/webhooks/nudj",
      "httpMethod": "POST",
      "isEnabled": true,
      "maxRetries": 5,
      "headers": {
        "X-API-Key": "your-webhook-secret",
        "X-Custom-Header": "custom-value"
      }
    }
  ]
}

Development Setup

Configuration for local development and testing:

{
  "configs": [
    {
      "events": [
        "challenge-completion",
        "reward-distribution"
      ],
      "url": "https://webhook.site/unique-url",
      "httpMethod": "POST",
      "isEnabled": true,
      "maxRetries": 1,
      "headers": {
        "X-API-Key": "test-key"
      }
    }
  ]
}

Testing Your Webhook

Follow these steps to test your webhook configuration:

Step 1: Set Up a Test Endpoint

Webhook.site

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

ngrok

1. Install ngrok: brew install ngrok
2. Start your local server: node server.js
3. Create tunnel: ngrok http 3000
4. Use the HTTPS URL as your webhook endpoint

RequestBin

1. Visit requestbin.com
2. Create a new bin
3. Copy the bin URL
4. Use it as your webhook URL

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:

Action	Triggered Event	Expected Payload
Complete a challenge	challenge-completion	Contains challengeId, userId
Earn rewards	reward-distribution	Contains points, XP, rewards
Unlock achievement	achievement-completion	Contains achievement details
Purchase from shop	shop-purchase	Contains purchase details
Like a post	post-like	Contains 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

Webhook not receiving events

• 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

Authentication errors

• Verify custom headers match exactly
• Check for case sensitivity in header names
• Ensure HTTPS is used (not HTTP)

Payload validation failures

• Compare received payload with documentation
• Check JSON parsing for large payloads
• Verify character encoding (UTF-8)

Intermittent failures

• Check for timeout issues (> 5 seconds)
• Monitor server resource usage
• Review network connectivity
• Check for rate limiting