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

​
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===="
}'

​
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"
}'

​
Examples

​
Further Reading