Go back to the main page

Getting Started with QuickBooks Online Webhooks

 

Webhooks finally have landed.

You can start rewriting your CDC polling code now . Well maybe not. As a prerequisite for this tutorial you need to be able to start up the qbo_api example app. If you haven't done that, do it now and come back.

  1. Switch into your local qbo_api directory.
  2. Start up the example app
    3.   $ shotgun example/app.rb
  3. Go to your QuickBooks Online API app you created for your start up example and click on the "Settings" link.
    4. Make sure you are in the "Development" and NOT "Production" area.
  4. Go down to the "Webhooks" section. You will see that we need to submit a URL so Intuit can POST webhook requests to. The standard way to do this in development is to use ngrok.
  5. Download ngrok and put it in a auto-loaded path. e.g. /usr/local/bin/
  6. Fire up ngrok on port 9393.
    7.     $ ngrok http 9393
    Here is the output of the ngrok http 9393 command.
  7. Copy the https:// url that the ngrok generates.
  8. Next, go back to https://developer.intuit.com and put this URL with /webhooks added to the end of it.
    Add the ngrok URL plus /webhooks route in the app settings page.
  9. Enable "Estimate" events to receive webhooks and hit "Save".
    10. Now we are almost ready to test.
  10. Let's add the /webhooks route to the example app.
  11. Open up example/app.rb and add this post route.
    12.   
post '/webhooks' do
  request.body.rewind
  data = request.body.read
  puts JSON.parse data
  verified = verify_webhook(data, env['HTTP_INTUIT_SIGNATURE'])
  puts "Verified: #{verified}"
end
  12. Next, let's add the verify_webhook method.
    13.   
helpers do
  def verify_webhook(data, hmac_header)
    digest  = OpenSSL::Digest.new('sha256')    
    calculated_hmac = Base64.encode64(OpenSSL::HMAC.digest(digest, VERIFIER_TOKEN, data)).strip    
    calculated_hmac == hmac_header
  end
end
  13. You'll also need to require the openssl and base64 libraries.
    14. require 'openssl'
require 'base64'
  14. You are going to need to add the VERIFIER_TOKEN variable.
  15. Go back Intuit Developer and copy the verifier token to your clipboard.
    16. This section is at the 7:47 mark.
    Copying the verifier token.
  16. Add the verifier token to the .env file like so:
    17. ...  
export QBO_API_COMPANY_ID=1441111111
export QBO_API_VERIFIER_TOKEN=[put here]
  17. Then in the example/app.rb put in this (below the CONSUMER_SECRET constant):
    18. VERIFIER_TOKEN = ENV['QBO_API_VERIFIER_TOKEN']
    This section is at the 10:10 mark.
  18. Open up your sandbox that was used when performing Spinning up an example app step.
  19. Copy this URL (https://sandbox.qbo.intuit.com/app/estimate?txn=100) and paste into the address bar after logging into the sandbox to go directly to Estimate 1001.
  20. Change the Status from "Pending" to "Accepted" and hit "Save".
    21. You don't have to fill out the Accepted Status date.
  21. Go back the console where example app is running and look for the incoming request.
    22. Look here for the incoming webhook request.
    In took about 15 seconds but it arrives!
  22. From this point you want to parse the JSON, putting the results into a queue for backend processing.

Conclusion

QuickBooks Online Webhooks support is going to radically simplify syncing user actions on QBO to your app. I am planning on perhaps 2 more webhooks tutorials so sign up for the newsletter below. Lastly, make sure you read Intuit's Best Practices section.