Add new webhooks and customize webhook payload

Ever wonder how to add new webhook types? Or how to reduce the payload? Here is the tutorial for the plugin authors. It demos how to add the session and user notification event types as well as customization to the payload. You can also check the plugin on GitHub while reading.

If you’d like to have a new webhook type supported by the team, bring up a feature request instead.

Before started, make sure you already understand webhook guide.

New webhook event type

A new webhook event type is defined in the database so that Ember client and webhook can find relevant information.


Add a seed file in the following path of the plugin db/fixtures/001_custom_web_hook.rb.

WebHookEventType.seed do |b| = 100 # start with a relative large number so it doesn't conflict with the core type = "notification"

WebHookEventType.seed do |b| = 101 = "session"

Then putting SeedFu.fixture_paths << Rails.root.join("plugins", "discourse-webhooks-example", "db", "fixtures").to_s into the plugin.

Admin dashboard needs the text to display the new event type. Adding them in config/locales/client.<language-code>.yml:

          name: "Notification Event"
          details: "When there is a new notification."
          name: "Session Event"
          details: "When there is a login or logout."

2. Connect with the internal DiscourseEvent or hook on your own

add_model_callback(:notification, :after_commit, on: :create) do
  # you can enqueue web hooks anywhere outside the AR transaction
  # provided that web hook event type exists
  WebHook.enqueue_hooks(:notification, # event type name
                        notification_id:, # pass the relevant record id
                        # event name appears in the header of webhook payload
                        event_name: "notification_#{Notification.types[self.notification_type]}_created")

%i(user_logged_in user_logged_out).each do |event|
  DiscourseEvent.on(event) do |user|
    WebHook.enqueue_hooks(:session, user_id:, event_name: event.to_s)

3. Final step: Sidekiq Jobs

Adding a new method to the Jobs::EmitWebHookEvent:

Jobs::EmitWebHookEvent.class_eval do
  # the method name should always be setup_<event type name>(args)
  def setup_notification(args)
    notification = Notification.find_by(id: args[:notification_id])
    return if notification.blank? # or raise an exception if you like

    # here you can define the serializer, you can also create a new serializer to prune the payload
    # See also: `WebHookPostSerializer`, `WebHookTopicViewSerializer`
    args[:payload] =, scope: guardian, root: false).as_json

  def setup_session(args)
    user = User.find_by(id: args[:user_id])
    return if user.blank?
    args[:payload] =, scope: guardian, root: false).as_json

An aside note, the payload is sent as if you are an administrator browsing a Discourse site. Be careful for what you sent.

Payload customization

There are two ways to reduce the payload size.

  1. Define a custom serializer.
  2. Uses plugin filter.

The first one is explicit to do. The second one involves a plugin API where you have the power to modify the payload. This enables the possibility to slice the JSON, i.e. @Lapinot suggested.

Plugin::Filter.register(:after_build_web_hook_body) do |instance, body|
  if body[:session]
    body[:user_session] = body.delete :session

  body # remember to return the object, otherwise the payload would be empty

Final aside note, a {{plugin-outlet name="web-hook-fields"}} is now available in the web hook configuration page.

The plugin code is available under GitHub - erickguan/discourse-webhooks-example.

Thanks @erlend_sh to encourage me writing this tutorial and @tgxworld for sorting out the internals.


@fantasticfears Note that it isn’t recommended to run migrations in plugins. Instead I’ve updated the howto to create a fixture file that will automatically be run when db:migrate is invoked.


Fixture is better than migration but it doesn’t work with the plugin now. The plugin system includes only db/migrate but not fixture.

Ah ha I forgot to include the secret sauce.


I didn’t know there’s a new API register_seedfu_fixtures! Updated.


what do i have to do to make it just notification webhook and remove the session event ?

Can someone offer a hint here?

I need to submit this JSON payload when a new user is created:

{"email_address":"address of new user", "status": "subscribed"}

I guess I don’t know how to create a serializer.

This is easy.

class MySerializer < ApplicationSerializer
  attributes :email_address, :status

my_object = "address of new user", status: "subscribed")

@fantasticfears Thanks for the writeup!

It needs a bit of tweaking to take account of the changes introduced in this commit.

  • You no longer need a setup_ method in Jobs::EmitWebHookEvent.

  • There’s now a WebHook a class method for formatting custom payloads via a serializer:

    WebHook.enqueue_object_hooks(type, object, event, Serializer) 

Also, I’m wondering about the thinking behind namespacing the payload with the event type? This makes it a little harder to use endpoints you don’t fully control, which expect certain attributes in the body.

def build_web_hook_body(args, web_hook)
   if ping_event?(event_type)
     body[:ping] = 'OK'
     body[event_type] = args[:payload]

Can you help me update the guide?

This is mainly for possible extension. Additional information can be serialized to other keys. But we relies on serializers now so it’s more or less useless.



I’m trying to connect discourse to APP using webhooks.

I’ve done most of things but only one thing is left.

when you create a new topic in discourse, you send payload which has a lot of parameters to APP .

however, slack only get ‘text’ parameter. so I want to customize payload when using webhooks.

how do I change payload when using webhooks in discourse?


  "post": {
    "id": 19,
    "name": "user",
    "username": "user",
    "avatar_template": "/letter_avatar_proxy/v2/letter/u/c0e974/{size}.png",
    "created_at": "2018-07-20T06:24:33.205Z",
    "cooked": "<p>Cool, now i have you, haha</p>",
    "post_number": 6,
    "post_type": 1,
    "updated_at": "2018-07-20T06:24:33.205Z",
    "reply_count": 0,
    "reply_to_post_number": null,
    "quote_count": 0,
    "avg_time": null,
    "incoming_link_count": 0,
    "reads": 0,
    "score": 0,
    "topic_id": 11,
    "topic_slug": "this-is-new-topic",
    "topic_title": "This is new topic",
    "display_username": "user",
    "primary_group_name": null,
    "version": 1,
    "user_title": null,
    "moderator": false,
    "admin": true,
    "staff": true,
    "user_id": 1,
    "hidden": false,
    "trust_level": 1,
    "deleted_at": null,
    "user_deleted": false,
    "edit_reason": null,
    "wiki": false,
    "topic_posts_count": 6


   "topic_title": "This is new topic"


Hi, I’m trying to create a custom webhook following this guide and sample plugin, but I can not get my new custom event types to show up in the webhook UI. I tried installing the plugin linked in this guide in my local dev instance and the events in this example plugin do not show up either. I’m guessing something changed between 2017 and now which affects this?

Does anyone here know how to get the example plugin in this topic to work? I suspect the problem might be with the seeding code for the database since the new entries aren’t showing up in the /admin/api/web_hooks response. As it currently stands, this guide is not functional. Thanks!

Hey there! I think I need some help

I’m attempting to add a custom webhook, which I’ve been able to get working and it correctly sends the payload to the webhook URL. The only thing I’m unable to accomplish is to be able to enable the event when configuring the webhook in admin. I’ve followed the tutorial above registering the fixture but it’s not appearing in admin.

I’ve tried a couple of ways:

SeedFu.fixture_paths << Rails.root.join("plugins", "<plugin_name>", "db", "fixtures").to_s
register_seedfu_fixtures(Rails.root.join("plugins", "<plugin_name>", "db", "fixtures").to_s)


WebHookEventType.seed do |b| = 101 = "remove_like"

I also added this to locale:

      placeholder: placeholder
          name: "Remove Like Event"
          details: "When a user marks a post as the accepted or unaccepted answer."

Am I missing something? or am I supposed to do it in some other way?

Okay, it seems to have been a cache issue or something, when I installed it in another instance of discourse it did appear.