> ## Documentation Index
> Fetch the complete documentation index at: https://developers.learn.ink/llms.txt
> Use this file to discover all available pages before exploring further.

# Push notifications

> How to receive LearnInk notification events and forward them to users as push notifications

<Warning>
  If you're using the WebView integration, this setup is **required**. Users inside a WebView cannot receive push notifications directly from LearnInk — your app must receive notification events via webhook and forward them using your own push notification infrastructure. Without this, users will not receive training reminders or new assignment alerts.
</Warning>

## How it works

LearnInk generates notification events in two scenarios:

1. **Scheduled reminders** — automated reminders sent to users who have incomplete training
2. **Manual notifications** — notifications sent to users via the LearnInk admin dashboard (e.g. to announce new content or urgent training)

When a notification event fires, LearnInk sends a `notifications.sent` webhook payload to your registered endpoint. Your backend should extract the notification details and forward them to the relevant user using your own push notification sender (e.g. FCM, APNs, or a service like OneSignal).

***

## The `notifications.sent` event

The payload contains an array of notifications to be sent. Each notification in the array targets a single user.

```json theme={null}
{
  "api_version": "2022-11-15",
  "object": "event",
  "type": "notifications.sent",
  "timestamp": "2025-11-06T09:58:58.233Z",
  "data": {
    "notifications": [
      {
        "title": "Hi Mary!",
        "body": "Don't forget to complete your training today",
        "path": "/learning",
        "user_id": "le2bB6Fi4CMgrIOIqMCJryZb9PR2",
        "custom_id": "3c2143e4-3e8e-478a-bf0b-9dc6e284fa33",
        "phone_number": "+254705408079"
      }
    ]
  }
}
```

### Notification fields

| Field          | Type           | Description                                                                                                                                                        |
| -------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `title`        | string         | The notification title to display to the user                                                                                                                      |
| `body`         | string         | The notification body text                                                                                                                                         |
| `path`         | string         | The path to open in the WebView when the user taps the notification (e.g. `/learning`)                                                                             |
| `user_id`      | string         | LearnInk's internal user ID                                                                                                                                        |
| `custom_id`    | string \| null | The ID from your own system, passed when the user was created via the Identify API. Use this to look up the user in your own database.                             |
| `phone_number` | string \| null | The user's phone number, if provided. This is only present if you passed it via the Identify API or if the user registered with a phone number via standard login. |

<Note>
  `custom_id` is the most reliable way to identify the user in your own system and look up their push notification token. Use this rather than `phone_number`, which may be null if contact details were not provided.
</Note>

***

## What your backend should do

When you receive a `notifications.sent` event:

1. **Verify the webhook signature** — use the Svix headers to confirm the request is genuine (see [Webhook setup guide](/integration/webhook-guide))
2. **Return a `200` immediately** — before doing any processing, to acknowledge receipt
3. **For each notification in the array:**
   * Look up the user's push notification token using `custom_id` (or `user_id` as a fallback)
   * Send a push notification to that token using your push notification provider, using the `title` and `body` from the payload
   * When the user taps the notification, open the WebView at the URL path specified in `path`

***

## Handling the notification tap

When a user taps a push notification, your app should open the LearnInk WebView and navigate to the `path` specified in the notification payload. Follow the same authentication flow as a normal WebView open — call your backend to get a fresh sign-in token, then load the WebView with that token and the specified path.

For example, if `path` is `/learning`, the WebView URL should be:

```
https://m.learn.ink/{orgId}/learning?webview=true&token={token}
```

See the [WebView setup guide](/integration/webview-setup-guide) for details on constructing the WebView URL.

***

## Setting up the webhook

To receive `notifications.sent` events you need a registered webhook endpoint subscribed to that event type. See the [Webhook setup guide](/integration/webhook-guide) for step-by-step instructions.

When subscribing to events, make sure to include `notifications.sent` in your selection. If you select no events, you'll receive all events by default — but it's better to be explicit.