Note! This document is a work in progress. Anything with a strikethrough represents something that is under consideration, but not yet implemented.

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

This feature is currently in beta. Please email support to have a webhook enabled for one of your BusyConf Events.

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": "..." }
}

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

Testing and Troubleshoting

We recommend using RequestBin to both test and troubleshoot webhooks.