Avaza’s API supports sending you webhook notifications for a whole range of events.
Webhook notifications are used by developers to automate processes in one system as events happen in another. For example, developer could subscribe to ‘invoice_sent’ event, and have one of their webpages automatically notified whenever an invoice is Sent, or Marked as Sent in Avaza.
Subscribing to Webhooks
Developers can subscribe to webhook notifications in Avaza by sending an authenticated POST request to https://api.avaza.com/api/Webhook, and including a JSON dictionary in the body of the request:
{
"target_url": "string",
"event": "string"
}
for example:
{
"target_url": "https://yoursite.com/yourpage", "event": "contact_created" }
The api will respond with JSON containing the ID of the new Webhook subscription:
{
"ID": 10
}
Available Events
Here are the webhook events we currently support:
company_created
company_deleted
company_updated
contact_created
contact_deleted
contact_updated
invoice_created
invoice_sent
project_created
project_deleted
project_updated
task_created
timesheet_created
timesheet_deleted
timesheet_updated
You’re welcome to request support for additional webhooks.
Handling Webhooks
When you server page receives a webhook notification you should respond with a HTTP Status Code of 200 (OK).
We then know the webhook was delivered successfully. If we don’t receive a 200 response code, then we will start retrying the notification.
Webhook Reliability
Sometimes the web is unreliable, and sometimes webhooks might not get through. To handle this, we have implemented a system for automatically retrying webhook notifications.
Retries are sent with an exponential backoff policy, so we will attempt to send a retry with an increasing gap between retry attempts. (e.g. after approx 10 minutes, then after another 30 minutes, 90 minutes, 190 minutes etc)
We will retry up to 13 times.
Webhook Content
Each of the webhooks has varying content included in the hook, representing a snapshot of the entity at the point in time the event occurred.
The best way to see the format for any particular hook is to test it by sending the notification to the popular free Webhook Tester webhook testing site.
Sample webhook for timesheet_created:
[
{
"TimeSheetEntryID":18528, "Duration":4.0000, "EntryDate":"2016-05-23T00:00:00Z", "UserIDFK":93, "ProjectIDFK":137, "TimeSheetCategoryIDFK":21, "Notes":"notes go here", "TimeSheetEntryApprovalStatusCode":"Draft", "isBillable":true, "isInvoiced":false, "DateCreated":"2016-05-23T05:25:36.53Z", "DateUpdated":"2016-05-23T05:25:36.53Z"
}
]
Note that the webhooks include an JSON array containing a single item. This is by design, and you can assume this in your code.
