How to add new webhooks and customize webhook payload

(Erick Guan) #1

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 - fantasticfears/discourse-webhooks-example.

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

Discourse Webhooks - Help
(Alan Tan) #2

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

(Erick Guan) #3

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

(Alan Tan) #4

Ah ha I forgot to include the secret sauce.

(Erick Guan) #5

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

(Raja Ali) #6

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

(Jay Pfaffman) #7

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.

(Erick Guan) #8

This is easy.

class MySerializer < ApplicationSerializer
  attributes :email_address, :status

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

(Angus McLeod) #9

@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]

(Erick Guan) #10

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.