From 38166ea156a7d513916ddda47767dd8103c4cadb Mon Sep 17 00:00:00 2001 From: sohey Date: Wed, 22 Oct 2025 20:26:15 +0200 Subject: [PATCH 01/11] usenotif hook depreciated --- docs/mini-apps/core-concepts/notifications.mdx | 4 ++++ .../latest/components/minikit/hooks/useNotification.mdx | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/mini-apps/core-concepts/notifications.mdx b/docs/mini-apps/core-concepts/notifications.mdx index ffc058a8..1719b48a 100644 --- a/docs/mini-apps/core-concepts/notifications.mdx +++ b/docs/mini-apps/core-concepts/notifications.mdx @@ -129,6 +129,10 @@ Notification tokens are unique to each client app. This means a user can have se Use the `addMiniApp()` hook to prompt users to add your Mini App + + If you encounter a "Failed to add mini app" error, your webhook may be taking too long to respond. Webhooks must respond within 5 seconds to avoid timeouts from the Base app. + + ```tsx page.tsx highlight={11, 25-27} "use client"; diff --git a/docs/onchainkit/latest/components/minikit/hooks/useNotification.mdx b/docs/onchainkit/latest/components/minikit/hooks/useNotification.mdx index 676eb619..e39484f5 100644 --- a/docs/onchainkit/latest/components/minikit/hooks/useNotification.mdx +++ b/docs/onchainkit/latest/components/minikit/hooks/useNotification.mdx @@ -6,7 +6,7 @@ description: Send notifications via a backend proxy to users who saved your Mini Defined in [@coinbase/onchainkit](https://github.com/coinbase/onchainkit) -Notifications are not yet available in Base App but are coming soon. This documentation describes the upcoming API that will be available when notifications are fully deployed. +This hook is now deprecated. Please follow the [Notifications Guide](/mini-apps/core-concepts/notifications) to implement notifications. ebcbglkhecg From b6a2c416c62e660569a8a46f21191c1ea540922b Mon Sep 17 00:00:00 2001 From: sohey Date: Wed, 22 Oct 2025 20:32:34 +0200 Subject: [PATCH 02/11] updated warning --- .../latest/components/minikit/hooks/useNotification.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/onchainkit/latest/components/minikit/hooks/useNotification.mdx b/docs/onchainkit/latest/components/minikit/hooks/useNotification.mdx index e39484f5..f775476c 100644 --- a/docs/onchainkit/latest/components/minikit/hooks/useNotification.mdx +++ b/docs/onchainkit/latest/components/minikit/hooks/useNotification.mdx @@ -6,7 +6,7 @@ description: Send notifications via a backend proxy to users who saved your Mini Defined in [@coinbase/onchainkit](https://github.com/coinbase/onchainkit) -This hook is now deprecated. Please follow the [Notifications Guide](/mini-apps/core-concepts/notifications) to implement notifications. +This hook is now deprecated. Please follow the [Notifications Guide](/mini-apps/core-concepts/notifications) for implementation. ebcbglkhecg From 1d3ce23f3371726ea9dfeb74e4be5f669c5767bf Mon Sep 17 00:00:00 2001 From: sohey Date: Thu, 23 Oct 2025 20:20:03 +0200 Subject: [PATCH 03/11] removed --- .../latest/components/minikit/hooks/useNotification.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/onchainkit/latest/components/minikit/hooks/useNotification.mdx b/docs/onchainkit/latest/components/minikit/hooks/useNotification.mdx index f775476c..7ed61231 100644 --- a/docs/onchainkit/latest/components/minikit/hooks/useNotification.mdx +++ b/docs/onchainkit/latest/components/minikit/hooks/useNotification.mdx @@ -8,7 +8,7 @@ Defined in [@coinbase/onchainkit](https://github.com/coinbase/onchainkit) This hook is now deprecated. Please follow the [Notifications Guide](/mini-apps/core-concepts/notifications) for implementation. -ebcbglkhecg + Allows Mini Apps to send push notifications to users who have saved your app. Notifications require a backend proxy route to handle the actual delivery and enforce rate limiting. From c200e645573fa25b5470630c97082b8f32130e23 Mon Sep 17 00:00:00 2001 From: sohey Date: Thu, 23 Oct 2025 20:21:47 +0200 Subject: [PATCH 04/11] switched call out --- docs/mini-apps/core-concepts/notifications.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/mini-apps/core-concepts/notifications.mdx b/docs/mini-apps/core-concepts/notifications.mdx index 1719b48a..7c8711cc 100644 --- a/docs/mini-apps/core-concepts/notifications.mdx +++ b/docs/mini-apps/core-concepts/notifications.mdx @@ -130,7 +130,7 @@ Notification tokens are unique to each client app. This means a user can have se Use the `addMiniApp()` hook to prompt users to add your Mini App - If you encounter a "Failed to add mini app" error, your webhook may be taking too long to respond. Webhooks must respond within 5 seconds to avoid timeouts from the Base app. + Webhooks must respond within 10 seconds to avoid timeouts from the Base app. If you encounter a "Failed to add mini app" error, your webhook may be taking too long to respond. ```tsx page.tsx highlight={11, 25-27} From 438e09ca95841e7c54dc0a8fe4441fe905ad291b Mon Sep 17 00:00:00 2001 From: sohey Date: Thu, 23 Oct 2025 20:48:19 +0200 Subject: [PATCH 05/11] added async to switch statement --- .../mini-apps/core-concepts/notifications.mdx | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/docs/mini-apps/core-concepts/notifications.mdx b/docs/mini-apps/core-concepts/notifications.mdx index 7c8711cc..15f7d401 100644 --- a/docs/mini-apps/core-concepts/notifications.mdx +++ b/docs/mini-apps/core-concepts/notifications.mdx @@ -54,16 +54,22 @@ Notification tokens are unique to each client app. This means a user can have se // Return appropriate error responses with status codes 400, 401, or 500 } + //Return success immediately BEFORE processing + //This allows Neynar to mark the token as active + const response = Response.json({ success: true }) + + // Extract webhook data const fid = data.fid; const appFid = data.appFid; // The FID of the client app that the user added the Mini App to const event = data.event; - // Handle different event types + // Handle different event types + (async () => { + try { switch (event.event) { case "miniapp_added": - // Save notification details and send welcome notification if (event.notificationDetails) { await setUserNotificationDetails(fid, appFid, event.notificationDetails); await sendMiniAppNotification({ @@ -96,9 +102,14 @@ Notification tokens are unique to each client app. This means a user can have se await deleteUserNotificationDetails(fid, appFid); break; } - - return Response.json({ success: true }); + } catch (error) { + console.error("Error processing webhook:", error); } + })(); + + return response; // Neynar gets success immediately + +} ``` From 186c25e0d3268dedd33ae23508d6d69fabf32f95 Mon Sep 17 00:00:00 2001 From: sohey Date: Thu, 23 Oct 2025 20:48:35 +0200 Subject: [PATCH 06/11] added async to switch statement --- docs/mini-apps/core-concepts/notifications.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/mini-apps/core-concepts/notifications.mdx b/docs/mini-apps/core-concepts/notifications.mdx index 15f7d401..ed856056 100644 --- a/docs/mini-apps/core-concepts/notifications.mdx +++ b/docs/mini-apps/core-concepts/notifications.mdx @@ -82,7 +82,7 @@ Notification tokens are unique to each client app. This means a user can have se break; case "miniapp_removed": - // Delete notification details + // Delete notification details await deleteUserNotificationDetails(fid, appFid); break; @@ -98,18 +98,18 @@ Notification tokens are unique to each client app. This means a user can have se break; case "notifications_disabled": - // Delete notification details + // Delete notification details await deleteUserNotificationDetails(fid, appFid); break; } } catch (error) { console.error("Error processing webhook:", error); } - })(); + })(); - return response; // Neynar gets success immediately - -} + return response; // Neynar gets success immediately + + } ``` From a9eef29b7baa10ba74e1d3cd43acabe71a53eb68 Mon Sep 17 00:00:00 2001 From: sohey Date: Thu, 23 Oct 2025 21:03:20 +0200 Subject: [PATCH 07/11] added async to switch statement --- docs/mini-apps/core-concepts/notifications.mdx | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/mini-apps/core-concepts/notifications.mdx b/docs/mini-apps/core-concepts/notifications.mdx index ed856056..5b5c41cc 100644 --- a/docs/mini-apps/core-concepts/notifications.mdx +++ b/docs/mini-apps/core-concepts/notifications.mdx @@ -19,6 +19,7 @@ You will receive webhook events when users enable or disable notifications for y Notification tokens are unique to each client app. This means a user can have separate notification preferences for your Mini App across different clients (e.g., Farcaster, the Base app). Removing your Mini App in one client does not affect its status in other clients. + ## Implementation @@ -141,7 +142,17 @@ Notification tokens are unique to each client app. This means a user can have se Use the `addMiniApp()` hook to prompt users to add your Mini App - Webhooks must respond within 10 seconds to avoid timeouts from the Base app. If you encounter a "Failed to add mini app" error, your webhook may be taking too long to respond. + **Important: Webhook Response Timing** + + Webhooks must respond within 10 seconds to avoid timeouts from the Base app. If you encounter a "Failed to add mini app" error, your webhook may be taking too long to respond. + + Different client apps handle webhook responses differently: + + **Farcaster app**: Does not wait for webhook responses and does not require a success response to activate notification tokens + + **Base app**: Waits for the webhook to return a success response before activating the notification token. + + This means if your webhook processes token saving and sends notifications synchronously before returning a response, tokens may work on Farcaster but fail to activate on Base app. ```tsx page.tsx highlight={11, 25-27} From 4d274823469d982fd1bcca7122ac9d290fea5e59 Mon Sep 17 00:00:00 2001 From: sohey Date: Fri, 24 Oct 2025 14:39:05 +0200 Subject: [PATCH 08/11] added async to switch statement --- docs/mini-apps/core-concepts/notifications.mdx | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/docs/mini-apps/core-concepts/notifications.mdx b/docs/mini-apps/core-concepts/notifications.mdx index 5b5c41cc..51e3e88c 100644 --- a/docs/mini-apps/core-concepts/notifications.mdx +++ b/docs/mini-apps/core-concepts/notifications.mdx @@ -55,10 +55,6 @@ Notification tokens are unique to each client app. This means a user can have se // Return appropriate error responses with status codes 400, 401, or 500 } - //Return success immediately BEFORE processing - //This allows Neynar to mark the token as active - const response = Response.json({ success: true }) - // Extract webhook data @@ -67,13 +63,13 @@ Notification tokens are unique to each client app. This means a user can have se const event = data.event; // Handle different event types - (async () => { + try { switch (event.event) { case "miniapp_added": if (event.notificationDetails) { - await setUserNotificationDetails(fid, appFid, event.notificationDetails); - await sendMiniAppNotification({ + setUserNotificationDetails(fid, appFid, event.notificationDetails); + sendMiniAppNotification(fid, appFid, "Welcome to Base Mini Apps", "Mini app is now added to your client"); fid, appFid, title: "Welcome to Base Mini Apps", @@ -106,11 +102,9 @@ Notification tokens are unique to each client app. This means a user can have se } catch (error) { console.error("Error processing webhook:", error); } - })(); - return response; // Neynar gets success immediately + return response; - } ``` @@ -147,7 +141,7 @@ Notification tokens are unique to each client app. This means a user can have se Webhooks must respond within 10 seconds to avoid timeouts from the Base app. If you encounter a "Failed to add mini app" error, your webhook may be taking too long to respond. Different client apps handle webhook responses differently: - + **Farcaster app**: Does not wait for webhook responses and does not require a success response to activate notification tokens **Base app**: Waits for the webhook to return a success response before activating the notification token. From 85f3ae5f59b9d8af9e0c6b81ac6cac9e495548f7 Mon Sep 17 00:00:00 2001 From: sohey Date: Fri, 24 Oct 2025 16:08:49 +0200 Subject: [PATCH 09/11] removed await from both save notification and client behaviour --- .../mini-apps/core-concepts/notifications.mdx | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/mini-apps/core-concepts/notifications.mdx b/docs/mini-apps/core-concepts/notifications.mdx index 51e3e88c..06df5eb8 100644 --- a/docs/mini-apps/core-concepts/notifications.mdx +++ b/docs/mini-apps/core-concepts/notifications.mdx @@ -85,8 +85,8 @@ Notification tokens are unique to each client app. This means a user can have se case "notifications_enabled": // Save new notification details and send confirmation - await setUserNotificationDetails(fid, appFid, event.notificationDetails); - await sendMiniAppNotification({ + setUserNotificationDetails(fid, appFid, event.notificationDetails); + sendMiniAppNotification({ fid, appFid, title: "Ding ding ding", @@ -137,16 +137,7 @@ Notification tokens are unique to each client app. This means a user can have se **Important: Webhook Response Timing** - Webhooks must respond within 10 seconds to avoid timeouts from the Base app. If you encounter a "Failed to add mini app" error, your webhook may be taking too long to respond. - - Different client apps handle webhook responses differently: - - **Farcaster app**: Does not wait for webhook responses and does not require a success response to activate notification tokens - - **Base app**: Waits for the webhook to return a success response before activating the notification token. - - This means if your webhook processes token saving and sends notifications synchronously before returning a response, tokens may work on Farcaster but fail to activate on Base app. ```tsx page.tsx highlight={11, 25-27} @@ -363,3 +354,12 @@ Sent when a user disables notifications from, e.g., a settings panel in the clie "event": "notifications_disabled" } ``` +## Client App Behavior + +Different client apps handle webhook responses differently: + +**Farcaster app**: Does not wait for webhook responses and does not require a success response to activate notification tokens + +**Base app**: Waits for the webhook to return a success response before activating the notification token. + +This means if your webhook processes token saving and sends notifications synchronously before returning a response, tokens may work on Farcaster but fail to activate on Base app. \ No newline at end of file From 7f7cd78d99b65422d555b3e2aa8d344752da3a99 Mon Sep 17 00:00:00 2001 From: sohey Date: Fri, 24 Oct 2025 17:49:36 +0200 Subject: [PATCH 10/11] added moved under overview --- .../mini-apps/core-concepts/notifications.mdx | 20 +++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/mini-apps/core-concepts/notifications.mdx b/docs/mini-apps/core-concepts/notifications.mdx index 06df5eb8..c34d4092 100644 --- a/docs/mini-apps/core-concepts/notifications.mdx +++ b/docs/mini-apps/core-concepts/notifications.mdx @@ -13,6 +13,18 @@ To send a notification, make a `POST` request to the `url` with the user's notif You will receive webhook events when users enable or disable notifications for your app. When disabled, the notification token becomes invalid and should no longer be used. +## Client App Behavior + +Different client apps handle webhook responses differently: + +Farcaster app: Activates notification tokens immediately without waiting for a webhook success response. + +Base app: Waits for a successful webhook response before activating tokens. + + +If your webhook processes token saving and sends notifications synchronously before returning a response, tokens may work on Farcaster but fail to activate on Base app. + + ![notification-image-iphone](/images/minikit/notifications-sample.png) @@ -354,12 +366,4 @@ Sent when a user disables notifications from, e.g., a settings panel in the clie "event": "notifications_disabled" } ``` -## Client App Behavior - -Different client apps handle webhook responses differently: - -**Farcaster app**: Does not wait for webhook responses and does not require a success response to activate notification tokens - -**Base app**: Waits for the webhook to return a success response before activating the notification token. -This means if your webhook processes token saving and sends notifications synchronously before returning a response, tokens may work on Farcaster but fail to activate on Base app. \ No newline at end of file From 91b3dfa0001b8efa16a7fa7d6d73977876622eb4 Mon Sep 17 00:00:00 2001 From: sohey Date: Fri, 24 Oct 2025 18:46:25 +0200 Subject: [PATCH 11/11] added bold --- docs/mini-apps/core-concepts/notifications.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/mini-apps/core-concepts/notifications.mdx b/docs/mini-apps/core-concepts/notifications.mdx index c34d4092..ac6ac769 100644 --- a/docs/mini-apps/core-concepts/notifications.mdx +++ b/docs/mini-apps/core-concepts/notifications.mdx @@ -17,9 +17,9 @@ You will receive webhook events when users enable or disable notifications for y Different client apps handle webhook responses differently: -Farcaster app: Activates notification tokens immediately without waiting for a webhook success response. +**Farcaster app**: Activates notification tokens immediately without waiting for a webhook success response. -Base app: Waits for a successful webhook response before activating tokens. +**Base app**: Waits for a successful webhook response before activating tokens. If your webhook processes token saving and sends notifications synchronously before returning a response, tokens may work on Farcaster but fail to activate on Base app.