📡 Webhooks

Configuring webhooks

If you’d like to set-up webhooks on Pencil Spaces, you can configure webhooks in Settings > API & Integrations > Webhooks or use our POST /webhooks API

For authentication, we’ll include the webhook secret as a bearer token in the authentication header in all of our requests to your endpoints.

• Staging environment

  • Webhook URL

  • Secret

• Production environment

  • Webhook URL

  • Secret

Supported events

Space-User events

These are webhook events that affect a particular user during a session in a Space. We provide analytics for the following webhook events: 

• Join room: When a user joins a Space or a room within the Space during a session

• Leave room: When a user leaves a Space or a room within the Space during a session

• User enters background: When a user navigates to a different tab on their device

• User enters foreground: When a user returns back to the tab containing Pencil Spaces on their device

Space-User events have the following payload: 

   return {
     spaceId: // SpaceId,
     sessionId: // SessionId,
     timestamp: // Timestamp,
     eventType: // Any of joinSpace, leaveSpace, hideTab, unhideTab
     userId: // UserId
     roomId: // RoomId,
     userTabId: // UserTabId,
     _type: // ‘SPACE_USER’,
   };

Space-Session events

These are webhook events that pertain to a session in a Space. We provide analytics for the session ended event, which fires when analytics processing has completed for an event in a Space.

Space-Session events have the following payload:

   return {
     spaceId: // SpaceId,
     sessionId: // SessionId,
     timestamp: // Timestamp,
     eventType: // ‘SESSION_ENDED’,
     _type: // ‘SPACE_SESSION’,
   };

Space-Recording events

These are webhook events that pertain to a recording in a Space. We provide analytics for two events: 

• Recording available: When a recording has finished processing in a Space

• Transcript available: When a transcript and summary has finished processing in a Space

Space recording events have the following payload:

return {
     spaceId: // SpaceId,
     recordingId: // RecordingId,
     timestamp: // Timestamp,
     eventType: // ‘RECORDING_AVAILABLE’,
     _type: // ‘SPACE_RECORDING’,
   };

Schedule events

Schedule events fire when a scheduled event is created, updated, deleted, or cancelled. Use the eventId with GET /events/{id} to retrieve the full event details.

Schedule events have the following payload:

return {
  eventId: // Unique identifier for the scheduled event
  timestamp: // ISO 8601 timestamp of the change
  eventType: // EVENT_CREATED | EVENT_UPDATED | EVENT_DELETED | EVENT_CANCELLED
  updatedBy: // ID of the user who made the change
  recurringUpdateType?: // Optional: ALL | FUTURE | CURRENT
  _type: // 'SCHEDULE'
};

Depending on whether the event is part of a recurring event, the payload may differ:

• Non-recurring events:

  • The event fires once with no recurringUpdateType field

• Recurring events:

  • When a scheduled event is created, deleted, or cancelled, an event is fired for each instance of that Schedule event in the recurring series. In this case recurringUpdateType is set to ALL.

  • When a scheduled event is updated, an event is fired for each affected instance of that scheduled event in the recurring series. In these cases, recurringUpdateType is set to ALL, FUTURE, or CURRENT depending on the scope of the update.

Attendance events

Attendance events are triggered whenever an attendance status is changed or whenever an attendance note is added or updated.

Attendance events have the following payload:

return {
  eventId: // Unique identifier for the scheduled event
  userId:  // ID of the participant whose attendance status changed
  timestamp: // UTC timestamp when the update occurred
  updatedBy: // userId of the user who made the update
  prevStatus?: { // Optional: previous attendance status
    status: // One of PRESENT, LATE, ABSENT, EXCUSED
    notes?: // Optional
  },
  currentStatus: { // Latest attendance status
    status: // One of PRESENT, LATE, ABSENT, EXCUSED
    notes?: // Optional
  }
}

Additional details can be queried using the GET /attendance/{event_id} API endpoint.

Program & Cohort events

Program & Cohort events fire when a cohort is created, updated, or deleted. Use the cohortId with GET /programs/{programId}/cohorts/{cohortId} to retrieve the full cohort details.

Note: For deleted cohorts, the cohort record is no longer available via the API. We recommend storing relevant cohort details on your end if you need to reference them after deletion.

Program & Cohort events have the following payload:

return {
  cohortId: // Unique identifier for the cohort
  programId: // Unique identifier for the program the cohort belongs to
  timestamp: // ISO 8601 timestamp of the change
  eventType: // COHORT_CREATED | COHORT_UPDATED | COHORT_DELETED
  updatedBy: // ID of the user who made the change
  _type: // 'PROGRAM_AND_COHORT'
};

eventType:

• Cohort created: Fires when a new cohort is added to a program

• Cohort updated: Fires when a cohort’s name, organizers, or attendees are modified

• Cohort deleted: Fires when a cohort is deleted

Alert events

Alert events fire when a Control Center alert is created or updated. Use the alertId with GET /alerts/{alertId} to retrieve the full alert details.

Alert events have the following payload:

javascript

return {
  alertId: // Unique identifier for the alert
  alertType: // TEACHER_DECLINED_EVENT | EVENT_NO_SHOW
  timestamp: // ISO 8601 timestamp of the change
  eventType: // CREATE_ALERT | UPDATE_ALERT
  updatedBy: // ID of the user responsible for the change, or null if raised or closed by the system
  _type: // 'CONTROL_CENTER_ALERT'
};

eventType:

• Create alert: Fires when a new alert is raised

• Update alert: Fires when an alert's status, priority, or assignee is changed, including when the alert is closed

alertType:

• Teacher declined event: A teacher declined a scheduled event

• Event no show: No attendee joined a scheduled event

Note: The meaning of updatedBy depends on eventType:

• On CREATE_ALERT, it is the user whose action raised the alert, such as the teacher who declined an event. Alerts detected by the system rather than a user action, such as EVENT_NO_SHOW, return null.

• On UPDATE_ALERT, it is the user who made the change, such as the administrator who assigned or resolved the alert.

Additional events

Additional events can be made available on-request. Please contact Pencil Spaces support and we’d be happy to assist you.