Option to include URL in Webhook Text #2834

New Issue

OVERLORD · 2026-02-05T05:23:53+03:00

OVERLORD commented

2026-02-05 05:23:53 +03:00

Originally created by @exula on GitHub (Jun 8, 2022).

Describe the feature you'd like

I would like to add an option to the Webhooks system to include the URL (if it's present) in the text of the webhook payload.

I've done some preliminary looking at the code,

This would include a new database field,
Some settings in the webhook configuration view
Everything else should be able to be handled in the WebhookFormatter action.

I'm more than happy to open a PR and make this happen, just want to get some guidance and make sure it's something you would be willing to merge.

Describe the benefits this would bring to existing BookStack users

Currently, the Slack compatible webhook notifications are nice, but they are not very rich. A quick fix would be to include the URL in the text payload so users can at least click on the link in Slack.

Current example:
<User> created page My Awesome Test page

Proposed:

<User created page My Awesome Test page

https://foo.bar/books/foor/bar/my-awesome-test-page

Can the goal of this request already be achieved via other means?

The only other means I can think of would be to create a middle man webhook receiver that takes outbound webhooks from Bookstack and does some magic and spits Slack enhanced webhooks on the other end.

Have you searched for an existing open/closed issue?

I have searched for existing issues and none cover my fundemental request

How long have you been using BookStack?

0 to 6 months

Additional context

This would be a totally optional feature and default to false, so existing webhooks would not be changed. So its impact on the installs out there in the wild should be nothing.

Originally created by @exula on GitHub (Jun 8, 2022). ### Describe the feature you'd like I would like to add an option to the Webhooks system to include the URL (if it's present) in the text of the webhook payload. I've done some preliminary looking at the code, * This would include a new database field, * Some settings in the webhook configuration view * Everything else should be able to be handled in the WebhookFormatter action. I'm more than happy to open a PR and make this happen, just want to get some guidance and make sure it's something you would be willing to merge. ### Describe the benefits this would bring to existing BookStack users Currently, the Slack compatible webhook notifications are nice, but they are not very rich. A quick fix would be to include the URL in the text payload so users can at least click on the link in Slack. Current example: `<User> created page My Awesome Test page` Proposed: ``` <User created page My Awesome Test page https://foo.bar/books/foor/bar/my-awesome-test-page ``` ### Can the goal of this request already be achieved via other means? The only other means I can think of would be to create a middle man webhook receiver that takes outbound webhooks from Bookstack and does some magic and spits Slack enhanced webhooks on the other end. ### Have you searched for an existing open/closed issue? - [X] I have searched for existing issues and none cover my fundemental request ### How long have you been using BookStack? 0 to 6 months ### Additional context This would be a totally optional feature and default to false, so existing webhooks would not be changed. So its impact on the installs out there in the wild should be nothing.

OVERLORD added the 🔨 Feature Request label 2026-02-05 05:23:53 +03:00

OVERLORD closed this issue

2026-02-05 05:23:58 +03:00

OVERLORD commented

2026-02-05 05:24:01 +03:00

@ssddanbrown commented on GitHub (Jun 8, 2022):

Hi @exula,
Thanks for the clear request and offer of PR.
To be honest though, The existing text property of webhooks primarily exists as a convenience for quick integration with common applications. I don't really want to go down the path of adding many different configuration options for different formats/features/platforms since that becomes a pain to maintain.

As you suggested, a middle-man app would be one way to handle this to transform and handle webhook data as required.

Alternatively, webhook data can be customized using our logical theme system. This system allows system extension without editing core app files. I have a video guide for this system here.

Here's an example of a functions.php file that customizes webhook data to add the url, if existing, to the text property:

`functions.php`

<?php

use BookStack\Actions\Webhook;
use BookStack\Actions\WebhookFormatter;
use BookStack\Auth\User;
use BookStack\Facades\Theme;
use BookStack\Theming\ThemeEvents;

// Hook into the "WEBHOOK_CALL_BEFORE" theme event,
// which runs before the webhook data is formatted and sent.
Theme::listen(ThemeEvents::WEBHOOK_CALL_BEFORE, function (string $event, Webhook $webhook, $detail, User $initiator, int $initiatedTime) {

    // Use BookStack's default formatter to get our standard BookStack webhook data.
    $webhookData = WebhookFormatter::getDefault($event, $webhook, $detail, $initiator, $initiatedTime)->format();

    // If a URL exists in the webhook data, append it to the text message.
    if (!empty($webhookData['url'])) {
        $webhookData['text'] .= ' ' . $webhookData['url'];
    }

    // Return our array of data back from this theme event.
    // This will tell the webhook system to use our customized data
    // instead of using the default BookStack formatting logic.
    return $webhookData;
});

Note: the contents within the function are not assured to be stable so could break upon update without warning (Should be rare though).

Let me know whether or not this method works for you, or if further guidance is needed.

@ssddanbrown commented on GitHub (Jun 8, 2022): Hi @exula, Thanks for the clear request and offer of PR. To be honest though, The existing `text` property of webhooks primarily exists as a convenience for quick integration with common applications. I don't really want to go down the path of adding many different configuration options for different formats/features/platforms since that becomes a pain to maintain. As you suggested, a middle-man app would be one way to handle this to transform and handle webhook data as required. Alternatively, webhook data can be customized using our [logical theme system](https://github.com/BookStackApp/BookStack/blob/development/dev/docs/logical-theme-system.md). This system allows system extension without editing core app files. I have a [video guide for this system here](https://www.youtube.com/watch?v=YVbpm_35crQ). Here's an example of a `functions.php` file that customizes webhook data to add the url, if existing, to the text property: #### `functions.php` ```php <?php use BookStack\Actions\Webhook; use BookStack\Actions\WebhookFormatter; use BookStack\Auth\User; use BookStack\Facades\Theme; use BookStack\Theming\ThemeEvents; // Hook into the "WEBHOOK_CALL_BEFORE" theme event, // which runs before the webhook data is formatted and sent. Theme::listen(ThemeEvents::WEBHOOK_CALL_BEFORE, function (string $event, Webhook $webhook, $detail, User $initiator, int $initiatedTime) { // Use BookStack's default formatter to get our standard BookStack webhook data. $webhookData = WebhookFormatter::getDefault($event, $webhook, $detail, $initiator, $initiatedTime)->format(); // If a URL exists in the webhook data, append it to the text message. if (!empty($webhookData['url'])) { $webhookData['text'] .= ' ' . $webhookData['url']; } // Return our array of data back from this theme event. // This will tell the webhook system to use our customized data // instead of using the default BookStack formatting logic. return $webhookData; }); ``` Note: the contents within the function are not assured to be stable so could break upon update without warning (Should be rare though). Let me know whether or not this method works for you, or if further guidance is needed.

OVERLORD commented

2026-02-05 05:24:09 +03:00

@exula commented on GitHub (Jun 8, 2022):

@ssddanbrown
That solution is amazing! Thank you! That's a very powerful system indeed then!

Thank you for making such an awesome product!

@exula commented on GitHub (Jun 8, 2022): @ssddanbrown That solution is amazing! Thank you! That's a very powerful system indeed then! Thank you for making such an awesome product!

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#2834