​
Overview

Farcaster client applications can host mini apps. Allowing those mini apps to push notifications to users requires the host to generate user notifcation tokens, send signed messages to the mini-apps webhook, and accept notifications via webhook. Neynar provides a system to manage this complexity on behalf of the client app (mini app host).

​
Basic flow

In the following example we’ll imagine
  • “Hostcaster” - a Farcaster client that wants to support mini apps
  • “Cowclicker” - a mini app

​
Enabling Notfications

  1. User wants to enable notifications for Cowclicker
  2. Hostcaster posts a “notifications_enabled” event to Neynar
  3. Neynar generates a unique token, bundles it in a signed message, and posts it to Clowclicker’s webhook URL

​
Sending Notifications

  1. Cowclicker wants to send a notification to a Hostcaster user for whom they have a valid notification token
  2. Cowclicker sends the notification event to Neynar’s webhook including the token
  3. Neynar validates the token, hydrates some data, and queues the notification for Hostcaster
  4. Hostcaster listens to a Kafka topic and/or polls an API for a user’s notifications

​
Message signing

An event sent to a mini-app webhook must be a signed JFS messages. There are two supported signing approaches in this system. Hostcaster can sign the message with a user’s key if they have the ability to do so. Or, if Hostcaster instead uses the Neynar-hosted signer system then they can provide their signer_uuid when posting the unsigned event.

​
Neynar-signed route

This approach requires only one API request:
  1. POST /v2/farcaster/app_host/user/event with a valid signer_uuid and the required event data
curl --request POST \
  --url https://api.neynar.com/v2/farcaster/app_host/user/event \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_KEY' \
  --data '{
  "signer_uuid": "01973000-b000-ee00-e0e0-0ee0e00e00ee",
  "app_domain": "cowclicker.gov",
  "fid": 10101,
  "event": "notifications_enabled"
}'

​
Self-sign route

  1. GET /v2/farcaster/app_host/user/event to retrieve the message to be signed. This is particularly important for notification_enabled events because this is when a notification token is generated by Neynar
  2. Sign the message, serialize the entire bundle per JFS spec
  3. POST /v2/farcaster/app_host/user/event with the signed message
curl --request GET \
  --url 'https://api.neynar.com/v2/farcaster/app_host/user/event?app_domain=cowclicker.gov&fid=10101&event=notifications_enabled' \
  --header 'x-api-key: YOUR_KEY'
…Sign and serialize the message… 
curl --request POST \
  --url https://api.neynar.com/v2/farcaster/app_host/user/event \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_KEY' \
  --data '{
  "app_domain": "cowclicker.gov",
  "signed_message": "eyJmaWZXkifQ==.eyJleI1Mjd9.nx1CPzKje4N2Bw===="
}'

​
Notifications via Kafka

To access your stream of notifications from a Kafka queue you’ll need to work with a Neynar representative to obtain the necessary credentials. You will be granted access to a Kafka topic with a name like app_host_notifications_Your_App_Name which contains a message for each notification. If an app sends the same message to 100 users, you will see 100 messages in Kafka similar to the example below. Sample message: 
{
    "notification": {
        "notification_id": "rate-test-1755216706-10",
        "title": "Sample Notification Test 10",
        "body": "This is notification message body",
        "target_url": "https://test.com/notification/10"
    },
    "app_domain": "demo.neynar.com",
    "notification_neynar_id": "0198ab11-7c61-xxxx-xxxx-0affb68fda66",
    "fid": "18949",
    "timestamp": "2025-08-15T00:11:46.657Z",
    "app": {
        "name": "Wownar",
        "icon_url": "https://demo.neynar.com/logos/neynar.svg"
    }
}

​
Further Reading