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

# Action Webhooks

> React to individual action completions, not just challenge-level events.

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.

<Info>
  Action webhooks are useful for real-time personalisation and analytics. If you only need end-of-challenge events, stick with `challenge-completion`.
</Info>

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

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

```json theme={null}
{
  "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](/api-reference/admin/get-actions).

## Filtering by action or challenge

Combine `action-participation` with [entity-level filtering](/developer/webhooks/event-filtering) to subscribe to only a specific action or challenge:

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

| Event                  | Fires when                                            |
| ---------------------- | ----------------------------------------------------- |
| `action-participation` | A user finishes one action inside a challenge         |
| `challenge-completion` | The 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.

## Related

<CardGroup cols={2}>
  <Card title="Event Catalog" icon="list" href="/developer/webhooks/event-catalog">
    Full event list, including all action-related events.
  </Card>

  <Card title="Entity Filtering" icon="filter" href="/developer/webhooks/event-filtering">
    Scope subscriptions to specific actions or challenges.
  </Card>
</CardGroup>