Skip to main content
Most challenge events fire once per challenge completion. Action webhooks fire once per individual action completed inside a challenge — giving you a finer-grained signal when a user answers a quiz question, watches a video, clicks a link, or completes any of Nudj’s 28+ action types.
Action webhooks are useful for real-time personalisation and analytics. If you only need end-of-challenge events, stick with challenge-completion.

​
When to use action webhooks

  • Progressive personalisation: update a recommendation engine as each action is completed rather than waiting for the full challenge.
  • Granular analytics: feed a data warehouse with per-step engagement metrics.
  • Custom side-effects: trigger downstream workflows (e.g. email a partner) when a specific action type is completed, regardless of which challenge it belongs to.

​
The action-participation event

Subscribe to the action-participation event: 
curl -X PUT "https://{subdomain}.nudj.cx/api/v2/admin/webhooks/configs" \
  -H "x-api-token: YOUR_ADMIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "url": "https://your-app.com/webhooks/nudj",
      "httpMethod": "POST",
      "isEnabled": true,
      "maxRetries": 3,
      "events": ["action-participation"]
    }
  ]'

​
Example payload

{
  "id": "652f8a3c1e4f7d0012a3b4c5",
  "eventCategory": "action",
  "eventSubCategory": "action-participation",
  "organisationId": "5f7d1e2a...",
  "communityId": "5f7d1e2a...",
  "userId": "60f7b8c8e7d4a2b1c9e3f4a3",
  "eventSourceId": "60f7b8c8e7d4a2b1c9e3f4a4",
  "payload": {
    "actionId": "60f7b8c8e7d4a2b1c9e3f4a4",
    "actionType": "QUIZ_MULTIPLE_CHOICE",
    "challengeId": "60f7b8c8e7d4a2b1c9e3f4a0",
    "isCorrect": true,
    "completedAt": "2026-03-14T10:21:45.102Z",
    "pointsEarned": 10,
    "xpEarned": 5
  },
  "createdAt": "2026-03-14T10:21:45.102Z"
}
  • eventSourceId is the action participation ID, not the action definition. If you need the action definition, use payload.actionId.
  • payload.actionType matches the enum in action definitions.

​
Filtering by action or challenge

Combine action-participation with entity-level filtering to subscribe to only a specific action or challenge: 
{
  "events": ["action-participation"],
  "entityFilters": {
    "action-participation": ["60f7b8c8e7d4a2b1c9e3f4a4"]
  }
}

​
Volume expectations

Action webhooks fire far more frequently than challenge webhooks. A 5-action challenge fires 5 action-participation events plus 1 challenge-completion event per user completion. Plan accordingly:
  • Size your handler for peak burst throughput, not average.
  • Process asynchronously — acknowledge the delivery with 200 OK fast, then enqueue work.
  • Use entity filters to cut volume before it reaches your handler.

​
Action completion vs challenge completion

EventFires when
action-participationA user finishes one action inside a challenge
challenge-completionThe user finishes all required actions in a challenge
For typical loyalty flows, you only need challenge-completion. Reach for action-participation when you need real-time signals at the step level.

Event Catalog

Full event list, including all action-related events.

Entity Filtering

Scope subscriptions to specific actions or challenges.