📡 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.

Additional events

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