Avenue Webhooks
Get a signed HTTPS request from Avenue whenever an appointment or a recurring series changes. How to verify a request, the event object, every event type and how delivery works.
A webhook is a request Avenue sends to your server when something changes. You give us an address, and each time an appointment or a recurring series is created, changed or deleted, we POST the details to it within a few seconds.
| Section | What it covers |
|---|---|
| Get a subscription | What we need from you, and what you get back |
| Verify a request | Signature, replay protection and idempotency |
| Delivery | Timeouts, retries, ordering and duplicates |
| The event object | The headers and the outer body every request shares |
| Event types | Every type and when it is sent |
| The appointment object | data.appointment, field by field |
| The series object | data.series, field by field |
Get a subscription
Subscriptions are set up by the Avenue team. Email info@avenue2.au with:
- The address to send to. It must start with
https://. - The event types you want. You only receive the types you list.
We send back a signing secret that starts with whsec_. Keep it on your server. You need it to verify each request.
A subscription belongs to your agency account. You receive events for every client under it, and each request says which client it is about.
Verify a request
Three checks, in this order: the signature, the timestamp, and the event id.
Signature
Every request carries an Avenue-Signature header:
Avenue-Signature: t=1761800000,v1=3070b2fc204fffeeba15392fcfd45455938a42d80b570a2037170a1c05632cda| Part | What it holds |
|---|---|
t | When we sent the request, in Unix seconds |
v1 | Lowercase hex HMAC-SHA256 of t, a full stop and the raw request body, keyed with your signing secret |
To check it:
- Join
t, a full stop and the request body exactly as it arrived:1761800000.followed by the raw body. - Compute the HMAC-SHA256 of that text with your signing secret as the key, as lowercase hex.
- Compare the result with
v1in constant time. Reject the request if they differ.
Sign the raw bytes of the body. A body that has been parsed and turned back into text can differ in spacing and key order, and will not match.
In Node.js:
const crypto = require('node:crypto')
function isFromAvenue(rawBody, signatureHeader, secret) {
const parts = Object.fromEntries(
signatureHeader.split(',').map((part) => part.split('='))
)
const expected = crypto
.createHmac('sha256', secret)
.update(`${parts.t}.${rawBody}`)
.digest('hex')
const given = Buffer.from(parts.v1 ?? '', 'hex')
const wanted = Buffer.from(expected, 'hex')
return given.length === wanted.length && crypto.timingSafeEqual(given, wanted)
}Test values. These verify:
| Value | |
|---|---|
| Secret | whsec_test |
t | 1761800000 |
| Raw body | {"id":"evt_1"} |
v1 | 3070b2fc204fffeeba15392fcfd45455938a42d80b570a2037170a1c05632cda |
Replay protection
t is covered by the signature. Reject a request whose t is outside your tolerance of the current time. We recommend five minutes; the tolerance is yours to set.
A retry is signed again when it is sent, so it always carries a current t.
Idempotency
Delivery is at least once, so make your handler idempotent on the event id. Record each id you have processed, and answer a repeat with a 2xx without processing it again.
The id is the same on every send of an event. It is in the body and in the Avenue-Event-Id header.
Delivery
Response
Answer with any status from 200 to 299 within 10 seconds. If the work takes longer, store the request, answer, and do the work afterwards.
Anything else counts as not delivered: another status, no answer in time, or a redirect. We don't follow redirects, so give us the final address.
Retries
A request that isn't delivered is sent again, up to ten tries in all, over about 20 hours. The gaps between tries are 1, 5, 15 and 30 minutes, then 1, 2, 4, 6 and 6 hours.
After the tenth try we stop. If your server was down for longer than that, email us and we can send the missed events again.
Ordering
Requests are not ordered. We send several at once, and one that is being retried doesn't hold up the others, so a later change can reach you before an earlier one.
Every request carries the whole appointment or series as it is when sent, so:
- Read the state from
data, not from the event type. Thestatusin the body is the appointment's status now, even on a request that arrives late. - Create or overwrite your copy by its
id. Don't assumeappointment.createdarrives first.
Duplicates
The same event can arrive more than once, for instance when we don't receive your answer. See Idempotency.
The event object
Every request is a POST with a JSON body.
Headers
| Header | What it holds |
|---|---|
Content-Type | application/json |
Avenue-Signature | The send time and signature. See Verify a request |
Avenue-Event-Id | The same value as id in the body |
Body
{
"id": "evt_9f2c41d87a3b4e6f8c1d2a5b7e9f0c34",
"type": "appointment.rescheduled",
"created_at": "2026-11-20T02:14:00.000Z",
"client": {
"id": "57",
"name": "Richmond Auto",
"external_id": "grp_41b7"
},
"data": {
"appointment": {}
}
}| Field | Type | What it holds |
|---|---|---|
id | string | The event's id. Unique per event, and the same on every send of it |
type | string | What happened. One of the event types |
created_at | string | When it happened, as a UTC timestamp |
client | object | The client the event is about |
client.id | string | Avenue's id for the client |
client.name | string | The client's name |
client.external_id | string or null | Your own id for that client, if you gave us one |
data | object | Holds one key, set by the type |
data.appointment | object | Present for appointment.* types. See The appointment object |
data.series | object | Present for appointment_series.* types. See The series object |
Every id is a string. Store and compare it as text, and don't read meaning into its format.
Event types
Appointment types
These carry data.appointment.
| Type | Sent when |
|---|---|
appointment.created | A single appointment is booked |
appointment.confirmed | Its status becomes confirmed |
appointment.started | Its status becomes in_progress |
appointment.completed | Its status becomes completed |
appointment.cancelled | Its status becomes cancelled |
appointment.no_show | Its status becomes no_show |
appointment.reopened | Its status goes back to pending |
appointment.rescheduled | Its start, its end or its all-day setting changes |
appointment.details_changed | Its title, notes, location or customer details change |
appointment.deleted | It is deleted |
appointment.restored | A deleted appointment is brought back |
One save can send two events. Moving an appointment and confirming it at the same time sends appointment.confirmed and appointment.rescheduled.
Series types
These carry data.series. A recurring appointment is a series. A change to a series can touch hundreds of appointments, so it sends one request for the series and none for the appointments in it.
| Type | Sent when |
|---|---|
appointment_series.created | A repeating appointment is created, or a single appointment is made to repeat |
appointment_series.updated | The series is edited or shortened, or is extended further ahead |
appointment_series.deleted | The series is deleted, or stops repeating |
A split. Editing a series from one appointment onwards splits it in two. You get appointment_series.updated for the original series, which now ends earlier, and appointment_series.created for the new one. The later appointments keep their ids and move to the new series.
An extension. Avenue creates a series' appointments about a year ahead at most. When the calendar in Avenue is opened near the end of what exists, the series is extended. That sends one appointment_series.updated for the series, listing every appointment in it including the new ones. It does not send a request per new appointment.
How appointments in a series reach you
- An appointment created by a series does not send
appointment.created. It is listed in the series request, underdata.series.occurrences. - Changing one appointment in a series on its own sends that appointment's own event, as per Appointment types, with
series_idset. - So the first request to mention an appointment can be a series request or the appointment's own event, and requests are not ordered. Create or overwrite your copy by its
idin both cases.
The appointment object
data.appointment is the whole appointment as it is when we send the request, not only the part that changed.
{
"id": "evt_9f2c41d87a3b4e6f8c1d2a5b7e9f0c34",
"type": "appointment.rescheduled",
"created_at": "2026-11-20T02:14:00.000Z",
"client": { "id": "57", "name": "Richmond Auto", "external_id": "grp_41b7" },
"data": {
"appointment": {
"id": "8812",
"status": "confirmed",
"start": "2026-11-04T09:00:00+11:00",
"end": "2026-11-04T10:00:00+11:00",
"all_day": false,
"time_zone": "Australia/Melbourne",
"location": { "id": "311", "name": "Richmond" },
"customer": {
"name": "Sam Lee",
"phone": "+61412341234",
"email": "sam@example.com"
},
"title": "Initial consultation",
"notes": "Call ahead",
"series_id": "44",
"previous": { "start": "2026-11-03T09:00:00+11:00" }
}
}
}Every path below is under data.appointment.
| Field | Type | What it holds |
|---|---|---|
id | string | The appointment's id |
status | string | pending, confirmed, in_progress, completed, cancelled or no_show |
start | string | Local time at the location, with its UTC offset |
end | string or null | As start |
all_day | boolean | true when the appointment is booked for the whole day and not a set time |
time_zone | string | The location's time zone, as an IANA name |
location | object or null | Where the appointment is |
location.id | string | The location's id |
location.name | string or null | The location's name |
customer | object | Who the appointment is for |
customer.name | string or null | |
customer.phone | string or null | In international format |
customer.email | string or null | |
title | string or null | |
notes | string or null | |
series_id | string | Present only when the appointment belongs to a series. Matches data.series.id |
deleted | boolean | Present, and true, only when the appointment has been deleted |
previous | object | Present only when this event changed a field in the body. Holds the old value of each changed field, and nothing else |
previous.status | string | On any status type |
previous.start | string | On appointment.rescheduled |
previous.end | string or null | On appointment.rescheduled |
previous.all_day | boolean | On appointment.rescheduled |
previous.title | string or null | On appointment.details_changed |
previous.notes | string or null | On appointment.details_changed |
previous.location | object or null | On appointment.details_changed. Holds id only |
previous.customer | object | On appointment.details_changed. Holds only the changed ones of name, phone and email |
previous describes what this one event changed. It is not the difference from the last request you received.
Some edits change things that aren't in the body, such as tags. Those send appointment.details_changed with no previous.
An appointment removed for good
When an appointment no longer exists at all, appointment.deleted carries only its id:
"data": { "appointment": { "id": "8812", "deleted": true } }The series object
data.series is the series as it is when we send the request, with every appointment in it.
{
"id": "evt_41b7c9d2e8f04a6b9c3d5e7f1a2b4c6d",
"type": "appointment_series.updated",
"created_at": "2026-11-20T02:14:00.000Z",
"client": { "id": "57", "name": "Richmond Auto", "external_id": "grp_41b7" },
"data": {
"series": {
"id": "44",
"time_zone": "Australia/Melbourne",
"rule": {
"freq": "weekly",
"interval": 1,
"by_weekday": ["tu"],
"ends": { "kind": "never" }
},
"deleted": false,
"appointment": {
"title": "Fleet service",
"duration_minutes": 60,
"location": { "id": "311", "name": "Richmond" },
"customer": {
"name": "Sam Lee",
"phone": "+61412341234",
"email": "sam@example.com"
},
"notes": "Call ahead"
},
"occurrences": [
{
"id": "9001",
"start": "2026-11-24T09:00:00+11:00",
"end": "2026-11-24T10:00:00+11:00",
"status": "confirmed",
"deleted": false,
"overridden": false
}
]
}
}
}Every path below is under data.series.
| Field | Type | What it holds |
|---|---|---|
id | string | The series' id. Matches series_id on its appointments |
time_zone | string | The time zone the series repeats in, as an IANA name |
deleted | boolean | true once the series has been deleted or has stopped repeating |
rule | object | How the series repeats. You don't need it to place the appointments: each one is in occurrences with its own times |
rule.freq | string | daily, weekly, monthly or yearly |
rule.interval | integer | Every how many. 2 with weekly is every second week |
rule.by_weekday | array of strings | Weekly only, and optional. The days it falls on, from mo, tu, we, th, fr, sa, su |
rule.monthly | object | Monthly only. One of the two forms below |
rule.monthly.kind | string | day_of_month or weekday |
rule.monthly.day | integer | With day_of_month: the day of the month |
rule.monthly.ordinal | integer | With weekday: 1 to 5 for the first to fifth, or -1 for the last |
rule.monthly.weekday | string | With weekday: one of the day codes above |
rule.ends | object | When the series stops. One of the three forms below |
rule.ends.kind | string | never, until or count |
rule.ends.date | string | With until: the last date, as YYYY-MM-DD |
rule.ends.count | integer | With count: how many appointments in all |
appointment | object | What each appointment in the series starts out as |
appointment.title | string or null | |
appointment.duration_minutes | integer | |
appointment.location | object or null | id and name, as on an appointment |
appointment.customer | object | name, phone and email, as on an appointment |
appointment.notes | string or null | |
occurrences | array of objects | Every appointment in the series, oldest first, up to 5,000 |
occurrences[].id | string | The appointment's id |
occurrences[].start | string | Local time with its UTC offset |
occurrences[].end | string or null | As start |
occurrences[].status | string | The appointment's status |
occurrences[].deleted | boolean | true when that appointment has been deleted |
occurrences[].overridden | boolean | true when that appointment was changed on its own, so its details differ from appointment. Keep what you hold for it |
The forms of rule.monthly:
{ "kind": "day_of_month", "day": 15 }
{ "kind": "weekday", "ordinal": -1, "weekday": "fr" }The forms of rule.ends:
{ "kind": "never" }
{ "kind": "until", "date": "2027-06-30" }
{ "kind": "count", "count": 12 }Reading occurrences
- A deleted appointment is always listed, with
deleted: true. - An appointment missing from a later list has left the series. It has not been deleted.
- On
appointment_series.deleted, the list holds the appointments deleted with the series. It is empty when the series only stopped repeating.
An appointment leaves a series in one of three ways:
| What happened in Avenue | Where the appointment is now |
|---|---|
| The series was edited from one appointment onwards | In the new series, listed in its appointment_series.created request under the same id |
| The repeat pattern changed, and an appointment that had been changed on its own no longer fits it | A single appointment |
| The series stopped repeating | A single appointment |
A series removed for good
When a series no longer exists at all, appointment_series.deleted carries only its id:
"data": { "series": { "id": "44", "deleted": true } }Need help?
Email info@avenue2.au to set up a subscription, change its address or event types, or have missed events sent again.