Skip to content

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 payload are in UTC, in the format "2023-08-25T16:58:00UTC"
  • The created timestamp 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 timeslot is 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 status is one of "Draft", "Live", "Disabled" or "Deleted"
  • gender is one of "m" (male), "f" (female), "c" (custom, described in gender_self_describe) or "o" (prefer not to say)
  • entry_status is 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
  • "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, 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"
}