How to version webhooks

Just like your API endpoints, your webhook events should be versioned. At Honeybadger we version our presenters to make it clear which event payload is being sent. When a user creates a new webhook in our UI, we save the current version with their webhook's URL, and we use that version when sending events:

class Webhooks::V1::UserCreated < Webhooks::Event
  attr_accessor :user

  def as_json
    {
      user_id: user.id,
      name: user.name,
      admin: user.admin?
    }
  end
end

Imagine that in the future we want to change the boolean admin property to a more versatile string named role— without impacting users. We can do so by bumping the version:

class Webhooks::V2::UserCreated < Webhooks::Event
  attr_accessor :user

  def as_json
    {
      user_id: user.id,
      name: user.name,
      role: user.role
    }
  end
end

Users who create a new webhook will now get V2 events, while current users will continue to get V1 events. If we want to deprecate V1 in the future, we could email the legacy users and give them a UI to upgrade their webhooks.