Skip to main content
By default, a webhook subscription fires for every matching event across your organisation. Entity-level filtering lets you narrow delivery to specific entities — for example, only fire challenge-completion for one flagship challenge, or only fire reward-claim for a particular reward asset.
Entity filters are optional. If you omit them, the webhook fires for all entities in the organisation.

​
Why filter by entity?

  • Reduce handler load: only process events your downstream system cares about.
  • Per-partner webhooks: point different webhook endpoints at different challenges (e.g. one challenge powers a partner’s co-marketing flow, the rest stay internal).
  • Avoid accidental fan-out: when you subscribe to a broad event like reward-distribution, filters stop you from processing unrelated rewards.

​
Configure a filter

Entity filters are set per subscription. In the admin panel, open a webhook config, select an event, and pick the entities from the dropdown: Via the Admin API, add an entityFilters map on the subscription: 
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": ["challenge-completion", "reward-claim"],
      "entityFilters": {
        "challenge-completion": ["65a0b1c2d3e4f5a6b7c8d9e0"],
        "reward-claim": ["65a0b1c2d3e4f5a6b7c8d9e1", "65a0b1c2d3e4f5a6b7c8d9e2"]
      }
    }
  ]'
Entity IDs must belong to entities visible to the token’s organisation. Filtering by an ID from a different org is rejected.

​
Event → entity mapping

Different events key off different entity types:
EventEntity TypeeventSourceId on payload
challenge-started, challenge-completionChallengeChallenge ID
achievement-completionAchievementAchievement ID
reward-claim, reward-redemption, reward-distributionRewardReward ID
action-participationActionAction ID
auth.email, streak-extended(not filterable — organisation-wide)N/A
Check the Event Catalog for the full list.

​
Editing filters

Filters can be changed any time — changes take effect immediately for new events. Existing in-flight deliveries (already queued) finish using the filter state at the time they were enqueued.

Event Catalog

Every event Nudj can fire and the entities it attaches to.

Implementation Guide

Build your handler to trust the filtered event stream.