What are Webhooks?

Webhooks are “user-defined HTTP callbacks” that are triggered by events on one website and can be configured to invoke behavior on another website.

Webhooks are an easy way to send information from one app to another, using a HTTP POST that contains data either passed as simple POST keys and values, or in some other format, like JSON, or less commonly XML. Usually, webhooks are used to notify one system that something has been added, edited or removed in another system, along with more useful information around that event.


How are they useful?

Ok, here's an example. Maybe you have a web application that has customers, but you didn't write the billing code yourself. You use a payment processing or recurring billing service like Stripe. You might use an API call to create the customer record within Stripe when they sign up, so you'll have a record in both systems that a customer has signed up, but what about when they upgrade, downgrade, cancel their account, buy a new add-on or do something else equally important within the system? Each time a user does something important within Stripe, you can have them send a webhook to you, and you can either use that information to do something useful in your system (actually activating their upgrade/downgrade), sending a notification to yourself, adding them to your email list, sending them an email... the sky's the limit!


How do they work?

An application that supports webhooks will have some way to register a web address (or addresses) that it will send webhooks to. They'll also have documentation about the types of events that they send webhooks for, and what is contained in them. On the other end, you need to write code to look for keys that identify the type of webhook it is, and then process it.


How do I use them?

Here's a basic example of how you might handle an incoming webhook in Ruby:

def stripehook
  if params[:type] == "customer.created"
    @user = User.find(:first, :conditions => ["stripe_description = ?", params[:data][:object]["description"]])
    if @user != nil
      @user.stripe_id = params[:data][:object]["id"]
      @user.save
    end
  elsif params[:type] == "customer.subscription.created"
    @user = User.find(:first, :conditions => ["stripe_id = ?", params[:data][:object]["customer"]])
    if @user != nil and @user.stripe_id != nil
      @user.plan_type = params[:data][:object][:plan][:id]
      @user.paid = "y"
      @user.save
    end
  elsif params[:type] == "invoice.payment_failed"
    @user = User.find(:first, :conditions => ["stripe_id = ?", params[:data][:object]["customer"]])
    if @user != nil and @user.stripe_id != nil
      if @user.payment_failed_times < 3
        @user.payment_failed_times += 1
        UserMailer.deliver_card_expired_warning(@user) #send expiring email
      else
        @user.paid = "n"
        UserMailer.deliver_card_expired(@user) #send expired email
      end
      @user.save
    end
  elsif params[:type] == "invoice.payment_succeeded"
    @user = User.find(:first, :conditions => ["stripe_id = ?", params[:data][:object]["customer"]])
    if @user != nil and @user.stripe_id != nil
      if @user.payment_failed_times > 0
        @user.payment_failed_times = 0
        @user.paid = "y"
        UserMailer.deliver_email_receipt(@user, params[:data][:object]["id"], params[:data][:object]["amount_due"])
      else #normal payment, no need to reactivate
        UserMailer.deliver_email_receipt(@user, params[:data][:object]["id"], params[:data][:object]["amount_due"])
      end
      @user.save
    end
  end
end
        

Beyond Webhooks

Now it's time to blow your mind. What if, for a lot of use cases you didn't even have to write any code to handle webhooks to send yourself notifications, email your customer, or add them to your mailing list, or perform other nifty actions based on a webhook coming in?

Or, maybe you prefer to write notification code and code that connects to other APIs yourself, for full control/customization. However, you have multiple apps and want to be able to write your code once and have it work no matter what webhook is on the other end (basically turning any given webhook input into the same output that your already-written code can use).

What if you could do the exact same thing, but for just about any website that sends email notifications (some don't support webhooks, but everyone supports email)?

We, at Sense Labs, were tired of writing code to handle webhooks and spending time dealing with automated emails, so we built an app that does all of the above and more. It's called Dispatch. And you can try it now, for free.