Calendar Sync Webhooks

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 endpointto 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 Datafield 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:

Property	Type	Description
SyncId	Int64	A unique identifier for the calendar event
StartTime	DateTime	The formatted start date/time of the calendar event, in UTC
EndTime	DateTime	The formatted end date/time of the calendar event, in UTC
Subject	String	The subject of the event.
Body	String	The body of the event.
Location	String	The location of the event.
OwnerEmailAddress	String	The “owner” of the calendar event. For example, if a student is registering for an event, this field will contain that student’s email address.
EmailAddresses	String[]	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": "[e-mail]",
    "EmailAddresses": [
      "[e-mail]"
    ]
  }
}

delete_calendar_event

The save_calendar_event occurs when a calendar event is deleted. Has the following fields:

Property	Type	Description
SyncId	Int64	A unique identifier for the calendar event
OwnerEmailAddress	String	The “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": "[e-mail]"
  }
}