Webhook Callbacks

What are Webhooks?

Webhooks allow you to keep your application in sync with FreshBooks. You can subscribe to FreshBooks Webhooks to receive real-time notifications from FreshBooks to your application.

Webhooks are a simple mechanism for sending notifications between APIs using HTTP POST callbacks. Webhooks allow you to specify a URI that you would like FreshBooks to POST information to any time certain events happen in a system. For instance, if you would like to receive a notification every time one of your users creates an invoice in FreshBooks, you can register a callback for the invoice.create method.

Access Requirements

Access	Requires Authorization
Scopes	The scope required is based on the webhook being registered. See the webhook list below.

Using WebHooks

Webhooks can be created with a POST to the callbacks endpoint. In order to ensure that you are the true owner of a callback URI being registered, we’ve implemented a very simple verification mechanism. When a callback is first registered, we will automatically send an HTTP POST request containing a unique verification code as well as a unique id for the callback record being verified. Simply send the verification code and the callback id back to us via a PUT to the callback API and notifications will begin being sent to your registered callback URI. You can ask us to resend the verification code at any time with a PUT call containing a resend variable in the body.

FreshBooks does not currently guarantee the speed at which a webhook is delivered after an event has occurred, and delivery could range from a few seconds to several minutes.

NOTE: You may want to consider storing this verification code for future use, as it will be used as the secret to calculate signatures used to verify webhooks are from FreshBooks (see below).

Searches / Filters

/events/account/<ACCOUNT_ID>/events/callbacks?search[%Name%]=<SEARCH_TERM> will search %Field% with the %Filter Type%

Name	Field	Filter Type	Description
event	event	Special	matches event and parent event. Eg. `invoices` matches `invoices.create`, `invoices.delete`
uri	uri	Equals	matches exact uri
verified	verified	Equals	matches true or false

Field Descriptions

Field	Type	Description
name	string	The event registered for
object_id	int	The unique identifier of the webhook callback
verifier	bool	True if the webhook callback has been verified

Webhook Descriptions

When an event of the type registered occurs, FreshBooks will send a POST request to the registered URI with the following form-urlencoded parameters:

http://your_server.com/webhooks/ready?name=invoice.create&object_id=1234567&account_id=6BApk&user_id=1

This means that the user with the id ‘1’ in the account ‘6BApk’ created an invoice with the id ‘1234567’. You can then call the FreshBooks API invoice resource, passing in invoice id 1234567 in order to get details about the invoice.

Field	Type	Description
name	string	The event registered for (eg. estimate.create)
object_id	int	The unique identifier of the webhook callback
account_id	bool	The unique identifier of the FreshBooks account
user_id	bool	The unique identifier of the FreshBooks user that performed the action

Failed Callbacks

Once your Webhooks are set up and verified, you will start receiving events. If FreshBooks receives anything other than a 2xx HTTP response code (including 3xx HTTP redirection codes) we will consider the attempt as failed. Webhooks HTTP POST requests have a ten second timeout set, and if there is no response within this time then the attempt is also considered failed. To avoid timeouts, consider deferring app processing until after a response to the webhook has been sent.

Failed requests will be retried periodically. After several failures, the message will be dropped and no further delivery attempts will be made.

If the webhook URL registered returns only failures over a long period, FreshBooks may disable the webhook. It can be easily re-enabled later by resending the verification token.

Verifying Webhooks

Each Webhook sent by FreshBooks includes a header, X-FreshBooks-Hmac-SHA256, with a base64-encoded signature generated using with the data sent in the request and token originally sent in the web hook verification process as a secret.

When you receive the webhook, you can verify that it came from FreshBooks by computing the signature and comparing it against the header.

Valid Events

Events in FreshBooks are identified by the combination of a noun and a verb (i.e. invoice.create). You can subscribe to all supported events related to a noun by using only the noun part (i.e. invoice). Note that callbacks are notified when these events occur from within the FreshBooks application or from another application that uses the FreshBooks API.

Noun / Entity	Verb / Action	Supported Event	Scope
category	*	category	`user:expenses:read`
category	create	category.create
category	update	category.update
category	delete	category.delete
client	*	client	`user:clients:read`
client	create	client.create
client	update	client.update
client	delete	client.delete
estimate	*	estimate	`user:estimates:read`
estimate	create	estimate.create
estimate	update	estimate.update
estimate	delete	estimate.delete
estimate	sendByEmail	estimate.sendByEmail
expense	*	expense	`user:expenses:read`
expense	create	expense.create
expense	update	expense.update
expense	delete	expense.delete
invoice	*	invoice	`user:invoices:read`
invoice	create	invoice.create
invoice	update	invoice.update
invoice	delete	invoice.delete
invoice	sendByEmail	invoice.sendByEmail
item	*	item	`user:billable_items:read`
item	create	item.create
item	update	item.update
item	delete	item.delete
payment	*	payment	`user:payments:read`
payment	create	payment.create
payment	update	payment.update
payment	delete	payment.delete
project	*	project	`user:projects:read`
project	create	project.create
project	update	project.update
project	delete	project.delete
recurring	*	recurring	`user:invoices:read`
recurring	create	recurring.create
recurring	update	recurring.update
recurring	delete	recurring.delete
service	*	service	`user:billable_items:read`
service	create	service.create
service	update	service.update
service	delete	service.delete
tax	*	tax	`user:taxes:read`
tax	create	tax.create
v	update	tax.update
tax	delete	tax.delete
time_entry	*	time_entry	`user:time_entries:read`
time_entry	create	time_entry.create
time_entry	update	time_entry.update
time_entry	delete	time_entry.delete

Register for webhook callback

Request:

POST https://api.freshbooks.com/events/account/<account_id>/events/callbacks


{
    "callback": {
        "event": "invoice.create",
        "uri": "http://your_server.com/webhooks/ready"
    }
}

Response:

{
  "response": {
    "result": {
      "callback": {
          "callbackid": 2001,
          "id": 2001,
          "verified": false,
          "uri": "http://your_server.com/webhooks/ready",
          "event": "invoice.create"
      }
  }
}

Verify webhook callback

Request:

PUT https://api.freshbooks.com/events/account/<account_id>/events/callbacks/<callback_id>


{
    "callback": {
        "verifier": "scADVVi5QuKuj5qTjVkbJNYQe7V7USpGd"
    }
}

Response:

{
  "response": {
    "result": {
      "callback": {
          "callbackid": 2001,
          "id": 2001,
          "verified": true,
          "uri": "http://your_server.com/webhooks/ready",
          "event": "invoice.create"
      }
  }
}

Resend verification code

Request:

PUT https://api.freshbooks.com/events/account/<account_id>/events/callbacks/<callback_id>


{
    "callback": {
        "resend": true
    }
}

Response:

{
  "response": {
    "result": {
      "callback": {
          "callbackid": 2001,
          "id": 2001,
          "verified": false,
          "uri": "http://your_server.com/webhooks/ready",
          "event": "invoice.create"
      }
  }
}

List all webhook callbacks

Request:

GET https://api.freshbooks.com/events/account/<account_id>/events/callbacks

Response:

{
  "response": {
    "result": {
      "per_page": 15,
      "pages": 1,
      "total": 2,
      "page": 1,
      "callbacks": [
          {
            "callbackid": 2001,
            "id": 2001,
            "verified": true,
            "uri": "http://your_server.com/webhooks/ready",
            "event": "invoice.create"
          },
          {
            "callbackid": 2010,
            "id": 2010,
            "verified": true,
            "uri": "http://your_server.com/webhooks/ready",
            "event": "estimate.delete"
          }
      ]
    }
  }
}

Delete a webhook callback

Request:

DELETE https://api.freshbooks.com/events/account/<account_id>/events/callbacks/<callback_id>

Response:

{
  "response": {}
}

Register for webhook callback

Request: POST
https://api.freshbooks.com/events/account/<account_id>/events/callbacks


url = "https://api.freshbooks.com/events/account/<account_id>/events/callbacks"
payload = {'callback': {
    'event': "invoice.create",
    'uri': "http://your_server.com/webhooks/ready"
}
}

headers = {'Authorization': 'Bearer &ltBearer Token&gt', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
res = requests.post(url, data=json.dumps(payload), headers=headers)

Response:

{
  "response": {
    "result": {
      "callback": {
          "callbackid": 2001,
          "id": 2001,
          "verified": false,
          "uri": "http://your_server.com/webhooks/ready",
          "event": "invoice.create"
      }
  }
}

Verify webhook callback

Request: PUT
https://api.freshbooks.com/events/account/<account_id>/events/callbacks/<callback_id>


url = "https://api.freshbooks.com/events/account/<account_id&gt/events/callbacks/<callback_id>"
payload = {'callback': {
    'verifier': "scADVVi5QuKuj5qTjVkbJNYQe7V7USpGd"
}
}

headers = {'Authorization': 'Bearer &ltBearer Token&gt', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
res = requests.put(url, data=json.dumps(payload), headers=headers)

Response:

{
  "response": {
    "result": {
      "callback": {
          "callbackid": 2001,
          "id": 2001,
          "verified": true,
          "uri": "http://your_server.com/webhooks/ready",
          "event": "invoice.create"
      }
  }
}

Resend verification code

Request: PUT
https://api.freshbooks.com/events/account/<account_id>/events/callbacks/<callback_id>


url = "https://api.freshbooks.com/events/account/<account_id&gt/events/callbacks/<callback_id>"
payload = {'callback': {
    'resend': true
}
}

headers = {'Authorization': 'Bearer &ltBearer Token&gt', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
res = requests.put(url, data=json.dumps(payload), headers=headers)

Response:

{
  "response": {
    "result": {
      "callback": {
          "callbackid": 2001,
          "id": 2001,
          "verified": false,
          "uri": "http://your_server.com/webhooks/ready",
          "event": "invoice.create"
      }
  }
}

List all webhook callbacks

Request: GET
https://api.freshbooks.com/events/account/<account_id>/events/callbacks


url = "https://api.freshbooks.com/events/account/<account_id&gt/events/callbacks"

headers = {'Authorization': 'Bearer &ltBearer Token&gt', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
res = requests.get(url, data=None, headers=headers)

Response:

{
  "response": {
    "result": {
      "per_page": 15,
      "pages": 1,
      "total": 2,
      "page": 1,
      "callbacks": [
          {
            "callbackid": 2001,
            "id": 2001,
            "verified": true,
            "uri": "http://your_server.com/webhooks/ready",
            "event": "invoice.create"
          },
          {
            "callbackid": 2010,
            "id": 2010,
            "verified": true,
            "uri": "http://your_server.com/webhooks/ready",
            "event": "estimate.delete"
          }
      ]
    }
  }
}

Delete a webhook callback

Request: DELETE
https://api.freshbooks.com/events/account/<account_id>/events/callbacks/<callback_id>


url = "https://api.freshbooks.com/events/account/<account_id&gt/events/callbacks/<callback_id>"

headers = {'Authorization': 'Bearer &ltBearer Token&gt', 'Api-Version': 'alpha', 'Content-Type': 'application/json'}
res = requests.delete(url, data=None, headers=headers)

Response:

{
  "response": {}
}

Verify webhook signature

Using Flask:

import base64
import hmac
import hashlib
import json

from flask import Flask, request

def signature_match(verifier, request):
   signature = request.headers.get('X-FreshBooks-Hmac-SHA256')
   data = json.dumps(request.form)

   dig = hmac.new(
      verifier.encode('utf-8'),
      msg=data.encode('utf-8'),
      digestmod=hashlib.sha256
   ).digest()
   calculated_sig = base64.b64encode(dig).decode()

   return signature == calculated_sig