mirror of
https://github.com/BookStackApp/BookStack.git
synced 2026-02-05 00:29:48 +03:00
Notification webhook framework #132
Reference in New Issue
Block a user
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Originally created by @DeftNerd on GitHub (Jul 13, 2016).
It would be nice if there was a global settings page and the framework to enable activity log notifications.
Notification when a page is created/modified/deleted
Notification when a user is created/modified/deleted
Notification when a file is created/modified/deleted
Notifications could be sent to several possible endpoints, but Slack and Rocket.Chat would be likely good first choices. Eventual additions could be email or messenger platform notifications to the admins
@ghost commented on GitHub (Nov 16, 2016):
I support this suggestion. The ability to add a webhook for slack would remove quite a few other "nice to have" features from our wish list.
@dennisoderwald commented on GitHub (Feb 6, 2017):
+1
@Shackelford-Arden commented on GitHub (Mar 2, 2017):
Always a fan of webhooks! +1
@therealscottcarlow commented on GitHub (Mar 15, 2017):
Definite +1
@jacksonp2008 commented on GitHub (Mar 30, 2017):
+1, anything in the works for this? IF not, can you point me to where I might make the changes myself?
@ssddanbrown commented on GitHub (Apr 3, 2017):
Nothing currently in the works for this at the moment. Notifications is a wide topic so I'd say as a stage 1 to complete this issue the focus is put on the basics of the original issue description:
The Web-hook URL and the subscribed events should be configurable and multiple web hooks should be able to be configured. For now it may be best to keep the contents of these hooks simple, With just the common
textproperty within JSON as supported by slack, matter-most & teams.There's currently an activity service which all activity creation runs through so that may be the best place to manage these events.
After the implementation of this we can then move focus to user-level notifications and expanding admin level notifications.
I am a bit worried about the performance cost of expanding out a notification system like this on a PHP based application. Once it gets to the point that saving a page fires of a couple of web-hooks and a bunch of emails things will start to get slow. I know a queue could be implemented but that will complicate application requirements, installation and maintenance.
@PriyaPallavi commented on GitHub (Jun 27, 2017):
Hi @ssddanbrown , I am really interested in the idea of having notification webhook framework. I have divided it into three steps. They are:
Currently I am focusing on the first two modules.
Initial implementation can have the following:
Examples of such notifications are:
Please do give your feedback.
@s0n- commented on GitHub (Aug 15, 2017):
+1 for this as well - Slack is probably a great use case for this
@galaxyfeeder commented on GitHub (Nov 8, 2017):
+1 very interesting for slack
@jacksonp2008 commented on GitHub (Feb 6, 2018):
Still interested in some way to get notifications from bookstack when someone creates a page or comments. I see that slack has an RSS plugin, so if you output an RSS feed that might be a quick win and I could integrate into slack.
"The RSS integration allows you to subscribe to an RSS or Atom feed URL and receive updates in Slack. Feeds will be fetched periodically, and new items will be posted to the specified channel."
thanks all
@tdmalone commented on GitHub (Feb 6, 2018):
A temporary (far from ideal, but possible) way of doing this could be setting up a little service that connects directly to the DB, stores the ID of the last entry in the relevant table, and then checks periodically for new entries. It could then send notification of the new entries somewhere.
If getting notifications into Bookstack is difficult, would this be worth writing? I might be able to do it if it would help people.
@jonakoudijs commented on GitHub (Feb 6, 2018):
A small service that can run periodically sounds like a nice idea. This does not complicate the setup and configuring a cronjob is a default feature on almost every shared hosting company so you will retain compatibility.
Let me know if you are going down that road and if I can help out.
@Liandriz commented on GitHub (Jul 14, 2018):
+1 Rss feed.
@tommyz4 commented on GitHub (Sep 18, 2018):
Has there been any progress on email notifications? Is this in the RoadMap?
@ssddanbrown commented on GitHub (Sep 18, 2018):
@tommyz4 Kind of on the road map. Email notifications appears to be open under #935.
There's a little bit of conversation about this issue. Is one of the highest rated issues so won't go ignored. Email notifications would be an extension/continuation of this issue once in-place as per my comment here: https://github.com/BookStackApp/BookStack/issues/147#issuecomment-291268041
@mark-james commented on GitHub (Nov 8, 2018):
This feature plus the api feature #823 together would allow for custom workflows and automation. This would mean bookstack could stay simple yet developers could develop very specific use cases outside of the codebase. I think this could be very powerful.
@nekromoff commented on GitHub (Nov 22, 2018):
Basic RSS (with secret token for private access) would work well for any read-only "notifications" such as displaying latest edited items somewhere else etc.
@ezzra commented on GitHub (Dec 8, 2018):
Because we have a need for RSS in our team, I hacked a dirty feed solution in https://github.com/ezzra/BookStack/tree/dirty_feed or you can comment here in this fake pull request: https://github.com/BookStackApp/BookStack/pull/1165
It is actually working, if you want to reuse it (@nekromoff and others), commit it to your code. Then run
composer installand addAPP_FEED_TOKEN=xxxto your.env. Of course,xxxshould be any random string, that makes the feed accessible without logging in!Be aware! The code is really dirty and its just working without beeing pretty, so please keep in mind:
so you can see, its a fast dirty hack, but it works. It could be made better of course. But its a wrong way, because there much more needs to be a system internal solution for subscriptions where notifications can be created in different ways (email, OS notification, RSS, ...) only for specific user accounts. That is why I wont put more work into that dirty way here.
@nekromoff commented on GitHub (Dec 8, 2018):
Great, much appreciated. I am going to look into it and report back.
On Sat, Dec 8, 2018, 13:51 ezzra <notifications@github.com wrote:
@irman commented on GitHub (Apr 4, 2019):
Any update on this? Would love to contribute and help out, or even kickstart it.
@ssddanbrown commented on GitHub (Apr 4, 2019):
@irman Upcoming on the roadmap is an API for BookStack. That will likely provide a lot of the groundwork/cleanup for a feature like this. This feature may be part of that API process, Depending on how things go.
@ezzra commented on GitHub (Apr 4, 2019):
@ssddanbrown looks like this roadmap link is somehow broken :)
@ssddanbrown commented on GitHub (Apr 5, 2019):
@ezzra Whoops, thanks for letting me know, now updated.
@akurzawa commented on GitHub (Apr 8, 2019):
+1 :)
When I create page I would like to inform somehow the peoples that new page was created for them.
@BoxedBrain commented on GitHub (Aug 9, 2019):
+1
Laravel supports queues which we could run with "supervisor"!
https://laravel.com/docs/5.8/queues
@deividas-balysevas commented on GitHub (Dec 4, 2019):
+1
Email notifications, please!
@GameBurrow commented on GitHub (Jan 7, 2020):
Yes please. Need webhook or at least RSS feed so we can make our own.
@Albirew commented on GitHub (Jan 8, 2020):
There already are columns called "recently updated pages" and "recent activity". Isn't it possible to use same source to make an RSS feed for now?
@tomtrm commented on GitHub (Jun 18, 2020):
+1
@nnsense commented on GitHub (Jun 20, 2020):
I've just spent an hour configuring bookstack email backend, just to find out that this feature, which I've taken for granted, isn't available. So the whole point of configuring the mail backed is to send the registration email? I thought it was quite common for a team working on the same documentation to be notified on new/updated pages. I'm not speaking about something complex, such as a third party integration with slack for example, but the very basic "email update" should definitely be there.
@ssddanbrown commented on GitHub (Jun 21, 2020):
No, It can also be used for email confirmation & password resets 💌
@romainguerrero commented on GitHub (Sep 30, 2020):
+1 for Slack notifications !
@thimisc commented on GitHub (Sep 30, 2020):
+1 Slack notifications would be a great feature
@nothavelizard commented on GitHub (Dec 1, 2020):
+1 for email notifications
@dekardkrr commented on GitHub (Jan 19, 2021):
+1
@hwcltjn commented on GitHub (Mar 3, 2021):
+1
@GD1m commented on GitHub (Mar 15, 2021):
+1 for email notifications or any, please
@rubn-g commented on GitHub (Apr 6, 2021):
+1 for updates notifications, this issue is open since 5 years ago, any news about it?
@Redsandro commented on GitHub (May 22, 2021):
I've started a Bookstack for my old school club of 20 years ago. ❤️ And a decent lot of them ask me to "enable email notifications." I guess they just assume I can do that because they also received the registration email. 🧐
They want to know if anyone contributed to their memory/story, without having to come back and check the stories they wrote periodically.
@ssddanbrown could you reconsider the priority for this? It really helps motivate the club if people receive an email and want to check and amend the edits. 💪 A simplified minimalist implementation - even a beta one without subscription management that can only be enabled using an environment variable and simply emails all authors and/or all commenters, whichever is possible - would be beneficial and greatly appreciated.
@nekromoff commented on GitHub (May 22, 2021):
Just to set it straight. You now have access to Bookstack notifications via a notification URL, such as:
Example implementation for Laravel:
config.phpcode to import notifications:
You can easily plug your email system into this and send it out. However, right now there is no API endpoint for users. So you would have to either send everything to everyone or have a separate config for matching IDs to users (as
created_by,updated_byuser IDs are provided via API).@ssddanbrown commented on GitHub (May 22, 2021):
As an alternative solution, If anyone is handy with Laravel, you could attempt to use our backend-theme-system to listen to the
APP_BOOTevent we provide to then set event listeners on certain models.@Redsandro commented on GitHub (May 22, 2021):
@nekromoff Is this documented somewhere so I can better understand how to use this with a docker image?
I did search and found a puzzling lack of those keywords in the code; I suspect the actual function is provided through a dependency.
@nekromoff commented on GitHub (May 22, 2021):
The public documentation is unavailable. Only "hacking the Bookstack"
mentions it.
https://www.bookstackapp.com/docs/admin/hacking-bookstack/
However, once you have Bookstack installed, you can access it by using
/api/docs URL, where all the details are provided.
copy&paste of the first few paragraphs:
Getting Started Authentication
To access the API a user has to have the "Access System API" permission
enabled on one of their assigned roles. Permissions to content accessed via
the API is limited by the roles & permissions assigned to the user that's
used to access the API.
Authentication to use the API is primarily done using API Tokens. Once
the "Access
System API" permission has been assigned to a user, a "API Tokens" section
should be visible when editing their user profile. Choose "Create Token"
and enter an appropriate name and expiry date, relevant for your API usage
then press "Save". A "Token ID" and "Token Secret" will be immediately
displayed. These values should be used as a header in API HTTP requests in
the following format:
1
Authorization: Token <token_id>:<token_secret>
Here's an example of an authorized cURL request to list books in the system:
1
curl --request GET \
2
--url https://example.com/api/books \
3
--header 'Authorization: Token
C6mdvEQTGnebsmVn3sFNeeuelGEBjyQp:NOvD3VlzuSVuBPNaf1xWHmy7nIRlaj22'
If already logged into the system within the browser, via a user account
with permission to access the API, the system will also accept an existing
session meaning you can browse API endpoints directly in the browser or use
the browser devtools to play with the API.
Request Format
The API is primarily design to be interfaced using JSON so the majority of
API endpoints, that accept data, will read JSON request data although
application/x-www-form-urlencoded request data is also accepted. Endpoints
that receive file data will need data sent in a multipart/form-data format
although this will be highlighted in the documentation for such endpoints.
For endpoints in this documentation that accept data, a "Body Parameters"
table will be available showing the parameters that will accepted in the
request. Any rules for the values of such parameters, such as the data-type
or if they're required, will be shown alongside the parameter name.
On Sat, May 22, 2021 at 4:17 PM Sander Steenhuis @.***>
wrote:
@Redsandro commented on GitHub (May 22, 2021):
This is helpful. I hadn't found out about this yet. Thank you. 👍
@Redsandro commented on GitHub (May 23, 2021):
Just so I'm clear: The API allows you to access book/chapter/page metadata such as last update timestamp and user_id, but you cannot get the "recent activity" log (with both edits and comments) through API, correct? There is no way to fetch comment activity, and an edit notification script would need to poll all pages, correct?
Just to double check before I do something the hard way.
@ssddanbrown commented on GitHub (May 23, 2021):
@Redsandro That's correct, although you should be able to sort the results by the updated column and check those updated since last poll.
As an alternative, using the logical theme system posted above, you could quickly get something running like so (
functions.phpexample):Note: Only the theme functions themselves are considered somewhat stable, Most of the code there is not considered stable and subject to change upon any update.
@Redsandro commented on GitHub (May 24, 2021):
Thank you for the help. I don't feel at ease with PHP, otherwise I'd probably try to implement a proper notification system and do a PR. I will however share my
node.jsscript in case it may be useful.You can take multiple approaches. My approach stores the last edit dates in a
sqlite3file so that the script can be executed throughcron.Ideally you should
toucha dedicated log file andchownit to the same user that runscron:I run this once per day to make sort of an "daily digest", but you can run it every minute if you want everyone to receive notifications near realtime.
It's not smart. You'll need to hardcode the notification recipients. Everyone receives the updates, even if they trigger them themselves.
@ssddanbrown commented on GitHub (Dec 8, 2021):
I've started building a webhook implementation within PR #3099. To confirm, this PR (And this issue) are specific to the implementation of outbound HTTP webhooks. Other forms of notification & integration are outside the scope of the PR and this issue.
@jacksonp2008 commented on GitHub (Dec 8, 2021):
Excellent news!!
On Wed, Dec 8, 2021 at 06:44 Dan Brown @.***> wrote:
--
Regards,
-Steve
(415) 320-1102 https://www.google.com/voice/#phones
@ssddanbrown commented on GitHub (Dec 18, 2021):
Initial webhook implementation, as per my previous comment, now merged in within #3099 to be part of the next feature release.
Merry Christmas / happy holidays!
@rusty1281 commented on GitHub (Dec 26, 2021):
@ssddanbrown Tnx for this implementation but looks like I have an issue with this on one of my docker instances.
One instance works just fine, and the other that is running via a reverse proxy does not. The RP instance runs great until I set up webhook. So it all works, creating, deleting, commenting, the works. But as soon as I activate a webook (regardless of what events), all other operations are complete but with an error.
So for example, create a new page, hit save and I get an internal error. The upside is that the new page does get created, same as any other operation (delete, move, comment) but all happen after the internal error.
As soon as I delete the webhook, without even restarting the container, it all starts to work normally.
On my other, internal (non-RP) instance, it all works fine regardless of how many events or webooks I have active.
Has anyone had a chance to get the same or similar experience?
UPDATE: I have also tested this in a completely new docker instance with a fresh, empty DB, the same problem happens.
@unpokitodxfavor commented on GitHub (Jan 21, 2022):
I have the same problem, when I update to the latest version BookStack v21.12.2, when I access "settings", "webhook" I get the error:
Ha ocurrido un error
An unknown error occurred
@ssddanbrown commented on GitHub (Jan 21, 2022):
If you're having issues please follow the debugging documentation to get error detail from the error log, and open a new support issue here so we can get the correct information, as so you're not notifying all past subscribers of this issue.
@eubi86 commented on GitHub (Mar 15, 2023):
I know it's not the best way to write the code like this, but the notification works for book chapters and sites