Webhooks

What are Webhooks?

Use webhooks to be notified about events that happen inside your 12Twenty ecosystem. Webhooks allow you to build or set up integrations which subscribe to certain events on 12Twenty. It is an easy way to receive push notifications from 12Twenty to keep your system in sync without requiring polling! When an event you subscribe to is triggered on 12Twenty’s system, an HTTP POST request will be sent to your configured URL.

Webhook Terminology

  • Event an occurrence, such as a calendar appointment being created, deleted, etc. Each occurrence has a corresponding Event object.
  • Webhook Endpoint a URL defined by the customer to which 12Twenty sends events.

What are Webhooks used for?

Webhooks are used to ensure your system gets notified of the following types of events:
  • Appointment Bookings/Changes
  • Career-Center related Events
  • On-Campus Interview Changes

Enabling Push Notifications

To enable webhooks, you should provide the URL of your webhook endpoint to your account manager or technical expert at 12Twenty.

Request Payload Format

All requests made to your webhook will be sent in a standard format using JSON with an Event field and a Data field. The Event field will contain the type of the event and the Data field will contain a structured object with the associated data.
Sample POST payload that might be sent to the webhook:


{
  "Event": the type of the event,
  "Data" : a JSON object with information specific to the event
}



Request Headers

 12Twenty will provide an optional header named X-12TWENTY-TOKEN.
 X-12TWENTY-TOKEN will contain a shared token which is set-up with your account manager.
 It will only be included if one exists, and your web hook is set to use HTTPS.

Response Expectations

 The 12Twenty platform expects a 2xx response code for success.

Retries

 On failure, the platform will attempt to retry each webhook request up to 10 times.
 Time between each request utilizes exponential back-off.

Event Types

save_calendar_event

The save_calendar_event occurs when a calendar event is created or updated inside our system. This event will contain the following fields:
PropertyTypeDescription
SyncIdInt64A unique identifier for the calendar event
StartTimeDateTimeThe formatted start date/time of the calendar event, in UTC
EndTimeDateTimeThe formatted end date/time of the calendar event, in UTC
SubjectStringThe subject of the event.
BodyStringThe body of the event.
LocationStringThe location of the event.
OwnerEmailAddressStringThe “owner” of the calendar event. For example, if a student is registering for an event, this field will contain that student’s email address.
EmailAddressesString[]The email addresses of all relevant parties to the calendar event. For example, for an advising appointment, this field will contain the adviser’s and student’s address.
Sample POST request body JSON content that will be sent to your webhook:
{
  "Event": "save_calendar_event",
  "Data": {
    "SyncId": "Local:Event:12345;User:12345",
    "StartTime": "2016-02-27T19:00:00",
    "EndTime": "2016-02-27T21:00:00",
    "Subject": "Alumni Gathering",
    "Body": "Class of @DateTime.Now.Year Alumni Gathering,
    "Location": "Campus",
    "OwnerEmailAddress": "hsimpson@school.edu",
    "EmailAddresses": [
      "jsmith@school.edu"
    ]
  }
}

delete_calendar_event

The save_calendar_event occurs when a calendar event is deleted. Has the following fields:
PropertyTypeDescription
SyncIdInt64A unique identifier for the calendar event
OwnerEmailAddressStringThe “owner” of the calendar event. For example, if a student is registering for an event, this field will contain that student’s email address.
Sample POST request body JSON content that will be sent to your webhook:
{
  "Event": "delete_calendar_event",
  "Data": {
    "SyncId": "Local:Event:12345;User:12345",
    "OwnerEmailAddress": "jsmith@school.edu"
  }
}