Webhooks¶
Introduction¶
FIXR's Webhooks provide near real-time updates to be sent to your systems in response to certain triggers. Once a webhook destination has been configured, the endpoint will be sent data directly rather than having to poll an API for changes.
Configuration¶
Webhooks are triggered by events occurring on the FIXR platform. Webhooks are fired based on the following events:
| Event Name | Event Description |
|---|---|
Event created |
Fires a webhook when an event is created. |
Event updated |
Fires a webhook when an event is updated. |
Event published |
Fires a webhook when an event is changed to Live. |
Event ended |
Fires a webhook when an event has ended. |
Ticket sold |
Fires a webhook for each ticket type in a completed order. Buying three of one ticket type sends one webhook with quantity 3. |
Ticket scanned |
Fires a webhook whenever a ticket is checked in at the door. entry_status says whether entry was confirmed or denied. |
Customer updated |
Fires a webhook whenever a customer updates their profile details and/or contact preferences. |
Security¶
Authentication¶
Webhooks can optionally be configured to send an Authorization header with a bearer token so that your systems can verify webhooks are coming from the FIXR platform.
When configured, the token will be sent in the Authorization header in the form Bearer <token> where <token> is the configured token.
This token is fixed and configured when a webhook endpoint is set up on organiser.fixr.co.
For example, if the token was abcdef, the header would be Authorization: Bearer abcdef.
When data is received via webhook, your endpoint should check the token is provided and is correct.
HTTPS¶
All configured webhook URLs must use HTTPS.
Delivery¶
Each webhook is sent once. If your endpoint is unreachable or responds with an error, FIXR doesn't send that webhook again, so save the message somewhere that survives a restart (a database or a persistent queue) first, then respond with a 2xx status and do any slow processing afterwards.
Use message_id to recognise a message you have already processed, as in rare cases the same message can be delivered more than once.
Data Structures¶
Data is sent as an application/json POST request.
- Date/time strings in the
payloadare in UTC, in the format"2023-08-25T16:58:00UTC" - The
createdtimestamp of the message is in UTC, in RFC 3339 format with fractional seconds, e.g."2023-08-25T16:58:00.466Z". The number of fractional digits can vary. - A
timeslotis a single string holding the start and end of the slot, e.g."2023-09-22T04:00:00Z - 2023-09-22T05:00:00Z" - Monetary amounts are returned as strings, e.g
"15.25". Whole amounts have one decimal place, e.g."8.0" - An event's
statusis one of"Draft","Live","Disabled"or"Deleted" genderis one of"m"(male),"f"(female),"c"(custom, described ingender_self_describe) or"o"(prefer not to say)entry_statusis one of"Unchecked"(not checked in),"Confirmed"(entry confirmed) or"Denied"(entry denied)- Contact preference option strings can be one of the following:
"opt_in"- User has positively opted in to receiving marketing communications
"opt_out"- User has positively opted out of receiving marketing communications, or has no recorded preference
"soft_opt_in"- User has not explicitly opted in or out of receiving marketing communications and defaults to
true
- User has not explicitly opted in or out of receiving marketing communications and defaults to
"soft_opt_out"- User has not explicitly opted in or out of receiving marketing communications and defaults to
false
- User has not explicitly opted in or out of receiving marketing communications and defaults to
Trigger Response Structure¶
All responses to triggers will respond with the same structure outline:
{
"event": "Trigger e.g. event_created",
"payload": {"Examples": "see below"},
"created": "String timestamp of when the message was sent, e.g. 2023-09-20T10:57:15.466Z",
"message_id": "ID of the message",
"fixr_account_id": "Specific ID of the FIXR Event Organiser account from where the webhook was configured"
}
Example Trigger Responses¶
The following are examples of the body of a fired webhook POST request may contain for each trigger.
Not all fields will be populated. If a field is not applicable (for instance if a ticket holder does not disclose a gender), the field will be null.
Event Created¶
{
"event": "event_created",
"payload": {
"capacity": 150,
"category": "Courses, Training and Workshops",
"close_time": "2023-09-22T22:59:00UTC",
"created_at": "2023-09-20T10:57:14UTC",
"created_by": {
"user_uuid": "f68475c8-5a8e-4b1e-841f-13f37cc8a66b",
"first_name": "Harry",
"last_name": "Potter",
"email": "harry.potter@hogwarts.co"
},
"description": "Event Created Webhook Response Description",
"event_id": "919509149",
"event_url": "https://eventurl.com",
"last_entry": "2023-09-22T18:00:00UTC",
"name": "FIXR Event Created Webhook Response",
"open_time": "2023-09-22T04:00:00UTC",
"status": "Draft",
"tags": ["special-event", "lecture"],
"location": {
"location_id": "15128",
"name": "02 Arena",
"address": "London SE10 0DX",
"online": false,
"postcode": "SE10 0DX",
"country": "United Kingdom",
"city": "London",
"timezone": "Europe/London"
}
},
"created": "2023-09-20T10:57:15.466Z",
"message_id": "8552615258943695",
"fixr_account_id": "930327450"
}
Event Updated¶
The entire event metadata is sent on an event update, even if only a single field is updated
{
"event": "event_updated",
"payload": {
"capacity": 150,
"category": "Courses, Training and Workshops",
"close_time": "2023-09-22T22:59:00UTC",
"created_at": "2023-09-20T10:57:14UTC",
"created_by": {
"user_uuid": "f68475c8-5a8e-4b1e-841f-13f37cc8a66b",
"first_name": "Harry",
"last_name": "Potter",
"email": "harry.potter@hogwarts.co"
},
"description": "Updated Description",
"event_id": "919509149",
"event_url": "https://eventurl.com",
"last_entry": "2023-09-22T18:00:00UTC",
"name": "FIXR Event Created Webhook Response",
"open_time": "2023-09-22T04:00:00UTC",
"status": "Draft",
"tags": ["special-event", "lecture"],
"location": {
"location_id": "15128",
"name": "02 Arena",
"address": "London SE10 0DX",
"online": false,
"postcode": "SE10 0DX",
"country": "United Kingdom",
"city": "London",
"timezone": "Europe/London"
}
},
"created": "2023-09-20T10:57:15.466Z",
"message_id": "8552615258943696",
"fixr_account_id": "930327450"
}
Event Published¶
{
"event": "event_published",
"payload": {
"event_id": "919509149",
"name": "FIXR Event Created Webhook Response",
"status": "Live"
},
"created": "2023-09-20T12:57:15.466Z",
"message_id": "8552615258943697",
"fixr_account_id": "930327450"
}
Event Ended¶
{
"event": "event_ended",
"payload": {
"capacity": 150,
"category": "Courses, Training and Workshops",
"close_time": "2023-09-22T22:59:00UTC",
"created_at": "2023-09-20T10:57:14UTC",
"created_by": {
"user_uuid": "f68475c8-5a8e-4b1e-841f-13f37cc8a66b",
"first_name": "Harry",
"last_name": "Potter",
"email": "harry.potter@hogwarts.co"
},
"description": "Updated Description",
"event_id": "919509149",
"event_url": "https://eventurl.com",
"last_entry": "2023-09-22T18:00:00UTC",
"name": "FIXR Event Created Webhook Response",
"open_time": "2023-09-22T04:00:00UTC",
"status": "Live",
"tags": ["special-event", "lecture"],
"location": {
"location_id": "15128",
"name": "02 Arena",
"address": "London SE10 0DX",
"online": false,
"postcode": "SE10 0DX",
"country": "United Kingdom",
"city": "London",
"timezone": "Europe/London"
},
"total_revenue": [
{"currency": "GBP", "amount": "150.75"},
{"currency": "USD", "amount": "52.0"}
],
"tickets_sold": 150,
"tickets_transferred": 10,
"total_orders": 120
},
"created": "2023-09-22T23:10:02.466Z",
"message_id": "8552615258943698",
"fixr_account_id": "930327450"
}
Ticket Sold¶
{
"event": "ticket_sold",
"payload": {
"booking_fee": {
"amount": "0.82",
"currency": "GBP"
},
"event_id": "919509149",
"event_name": "FIXR Event Created Webhook Response",
"event_url": "https://eventurl.com",
"order_reference": "604bdd96",
"price": {
"amount": "8.0",
"currency": "GBP"
},
"promo_code": "PROMOCODE",
"reserved_at": "2023-09-20T11:11:05UTC",
"sold_at": "2023-09-20T11:11:17UTC",
"ticket_holders": [
{
"first_name": "Ron",
"last_name": "Weasley",
"email": "ron.weasley@hogwarts.co",
"date_of_birth": "1991-05-11",
"mobile_number": "+44726730425",
"gender": "m",
"gender_self_describe": null,
"user_uuid": "f68475c8-5a8e-4b1e-841f-13f37cc8a66b",
"contact_preferences_user_response": "opt_in"
}
],
"ticket_reference": "XHWFtRfJe3QTvkCsagzff3",
"ticket_type": "General Admission",
"ticket_type_category": null,
"ticket_type_id": "540568",
"timeslot": null,
"quantity": 3,
"location": {
"location_id": "15128",
"name": "02 Arena",
"address": "London SE10 0DX",
"online": false,
"postcode": "SE10 0DX",
"country": "United Kingdom",
"city": "London",
"timezone": "Europe/London"
}
},
"created": "2023-09-20T11:11:19.466Z",
"message_id": "8552135679096150",
"fixr_account_id": "930327450"
}
Ticket Scanned¶
{
"event": "ticket_scanned",
"payload": {
"entry_status": "Confirmed",
"event_id": "919509149",
"event_name": "FIXR Event Created Webhook Response",
"event_url": "https://eventurl.com",
"people_in": 3,
"ticket_holders": [
{
"first_name": "Ron",
"last_name": "Weasley",
"email": "ron.weasley@hogwarts.co",
"date_of_birth": "1991-05-11",
"mobile_number": "+44726730425",
"gender": "m",
"gender_self_describe": null,
"user_uuid": "f68475c8-5a8e-4b1e-841f-13f37cc8a66b",
"contact_preferences_user_response": "opt_in"
}
],
"ticket_reference": "XHWFtRfJe3QTvkCsagzff3",
"ticket_type": "General Admission",
"ticket_type_id": "540568",
"ticket_type_category": null,
"time_in": "2023-09-20T11:16:11UTC",
"timeslot": null,
"location": {
"location_id": "15128",
"name": "02 Arena",
"address": "London SE10 0DX",
"online": false,
"postcode": "SE10 0DX",
"country": "United Kingdom",
"city": "London",
"timezone": "Europe/London"
}
},
"created": "2023-09-20T11:16:11.466Z",
"message_id": "8552296675518248",
"fixr_account_id": "930327450"
}
Customer Updated¶
{
"event": "customer_updated",
"payload": {
"date_of_birth": "1991-11-05",
"email": "user@email.com",
"first_name": "Harry",
"gender": "m",
"gender_self_describe": null,
"last_name": "Potter",
"mobile_number": "+4445678910",
"preferred_language": "en",
"contact_preferences_user_response": "opt_in",
"user_uuid": "f68475c8-5a8e-4b1e-841f-13f37cc8a66b"
},
"created": "2023-09-20T10:57:15.466Z",
"message_id": "8552615258943696",
"fixr_account_id": "930327450"
}