Your BusyConf account has the ability to communicate with a web server whenever a change occurs within your Event. These WebHooks can be used to update an external list, deliver notifications, or even print badges for your attendees.

Setup

Callback

A webhook is sent as a HTTP POST request to the url that you specify. The POST request payload (request body) contains a JSON document, and adheres to the following format:

{
  "type": "<resource>.<action>",
  "fired_at": "2013-03-17T13:02:21-05:00",
  "event": { "id": "some-id", "name": "some-name", "more": "..." },
  "<resource>": { "id": "some-id", "some": "data", "more": "..." }
}

• The type key provides insight into what action occurred and on which resource.
• The fired_at key represents the time when the action originally occurred. All timestamps are in ISO 8601 format.
• The event key represents the BusyConf Event (Conference, Convention, Meeting, etc) under which this resource lives.
• The <resource> key represents the resource on which the action occured. For example, if the webhook type was ticket.created, the resource key would be ticket.

Responding

To acknowledge that you received the webhook without any problem, your server should return a 200 HTTP status code. Any other information you return in the request headers or request body will be ignored. Any response code outside the 2xx range, including 3xx codes, will indicate to BusyConf that you did not receive the webhook. When a Webook is not received for whatever reason, BusyConf will continue trying to send the webhook up to 18 times (with exponential backoff) within a 5 day period.

Again, the server MUST return a 2xx success response to acknowledge receipt – even if you do not take action on a particular hook and locally ignore the message as invalid.

Hook Types

WebHook types follow a naming convention of <resource>.<action>

Event Hooks (event.<action>)

These hook types describe changes your BusyConf Event itself. These JSON payloads will only include an event key, because the resource and the event are the same.

Hook Type	Description
event.created	(not yet implemented)
event.updated	(not yet implemented)

Ticket Hooks (ticket.<action>)

These hook types describe changes to tickets within your BusyConf Event.

Hook Type	Description
ticket.created	Occurs whenever a new ticket is successfully created.
ticket.updated	Occurs whenever an existing ticket is successfully updated (The cancelled_at will be set for cancelled tickets. It will be null for active or reinstated tickets).

Payment Transaction Hooks (payment_transaction.<action>)

TBD

Ticket Type Hooks (ticket_type.<action>)

TBD

Ticket Offer Hooks (ticket_offer.<action>)

TBD

Discount Code Hooks (discount_code.<action>)

TBD

Payload Example

{
  "type": "ticket.created",
  "fired_at": "2013-03-17T13:02:22-05:00",
  "event": {
    "id": "51468d3ec2e4dc01c5000001",
    "name": "Alpha Conference",
    "short_name": "AlphaConf",
    "subdomain": "alphaconf",
    "url": "http://alphaconf.org",
    "time_zone_name": "Eastern Time (US & Canada)",
    "created_at": "2013-03-12T16:12:43Z",
    "updated_at": "2013-03-17T09:32:56Z"
  },
  "ticket": {
    "id": "51468d5bc2e4dc01c5000002",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "company": "Example, Inc.",
    "job_title": "Manager",
    "twitter_username": "johndoe",
    "phone": "123-555-1234",
    "confirmation_number": "DEF456",
    "paid": "150.00",
    "cancelled_at": null,
    "created_at": "2013-03-17T13:02:21Z",
    "updated_at": "2013-03-17T13:02:21Z",
    "purchase": {
      "id": "51468d5ec2e4dc01c5000003",
      "amount": "150.00",
      "reason": "Conference Admission (Early Bird)",
      "payment_transaction_id": "51529a64c2e4dc3eea000017",
      "billing_first_name": "Bob",
      "billing_last_name": "Smith",
      "billing_company": "Example, Inc.",
      "billing_email": "bob@example.com",
      "billing_street_address": "123 Fake St",
      "billing_postal_code": "12345",
      "created_at": "2013-03-17T13:02:21Z"
    },
    "discounts": [{
      "id": "51529a64c2e4dc3eea00001a",
      "amount": "-150.00",
      "reason": "50% Discount \"HALFOFF\"",
      "created_at": "2013-03-17T13:02:21Z"
    }],
    "refunds": [],
    "ticket_type": {
      "id": "51468d66c2e4dc01c5000004",
      "name": "Conference Admission"
    },
    "ticket_offer": {
      "id": "51468d6dc2e4dc01c5000005",
      "name": "Early Bird"
    },
    "custom_answers": [{
        "id": "51468d78c2e4dc01c5000006",
        "label": "Shirt Size",
        "answer": "Men's XL"
      },{
        "id": "51468d7ec2e4dc01c5000007",
        "label": "Dietary Preference",
        "answer": "Gluten Free"
      }
    ]
  }
}

Securing WebHooks

You may use a HTTP or a HTTPS url for webhooks. HTTP is sufficient, but HTTPS can be useful if your data is sensitive or if you wish to protect against replay attacks.

Because your endpoint will be wide-open on the Internet, you might not want others to be able to submit random requests to your systems. It is recommended that you keep the URL private or include a secret key in the URL that you provide and check that on subsequent webhook requests.

HTTP Headers

• Content-Type: application/json: All HTTP POSTs will include this content type.
• X-BusyConf-Hook-Type: <resource>.<action>: To help short-circuit parsing the JSON payload, this header matches the type field. Use this if you’re only responding to certain webhook types and do not need to parse every JSON payload. Remember to still return a 2xx success response if you ignore a hook.

Testing and Troubleshoting

We recommend using RequestBin to both test and troubleshoot webhooks.