Webhooks¶

Introduction¶

FIXR's Webhooks provider 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 occuring on the FIXR platform. Webhooks are fired besd 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 whenever a ticket is purchased.
`Ticket scanned`	Fires a webhook whenever a ticket is scanned (admitting the attendee to the venue).
`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.

Data Structures¶

Data is sent as an application/json POST request.

Date/time strings are in the format "2023-08-25T16:58:00Z"
Monetary amounts are returned as strings, e.g "15.25"
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
"soft_opt_in"
- User has not explicitly opted in or out of receiving marketing communications and defaults to true
"soft_opt_out"
- User has not explicitly opted in or out of receiving marketing communications and defaults to false

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",
  "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:15UTC", 
  "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:15UTC", 
  "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:15UTC",
  "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.00"}
    ],
    "tickets_sold": 150,
    "tickets_transferred": 10,
    "total_orders": 120
  },
  "created": "2023-09-22T22:59:00UTC",
  "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:19UTC",
  "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:11UTC",
  "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:15UTC", 
  "message_id": "8552615258943696",
  "fixr_account_id": "930327450"
}