Post-interview feedback: Calendar → Slack → Typeform → Notion

Enable the Calendar API and configure OAuth consent

Google Cloud Console → APIs & Services → Library → search "Google Calendar API" → Enable. Then APIs & Services → OAuth consent screen → set App name and User type (Internal only works inside a Workspace domain; External + Testing mode is enough for a team running this on itself).

Create a Web application OAuth client

Credentials → Create Credentials → OAuth client ID → Web application, not Desktop app — the Desktop quickstart only covers a one-off interactive login, not a refresh token an unattended poller can renew silently. Build the authorization URL with access_type=offline, or the access token has no way to renew once it expires.

Scope read-only, and poll the booking calendar — not each interviewer's own

Scope to calendar.events.readonly. Point the poller at the single calendar your interview-booking flow writes events to (the recruiting coordinator's or ATS's own calendar), not at every interviewer's personal calendar — enumerating those would need Workspace domain-wide delegation, an admin-only setup step this workflow doesn't budget for. State that calendar's owner plainly when you configure the poller; defaulting to "my own primary calendar" by habit is the usual misconfiguration.

https://www.googleapis.com/auth/calendar.events.readonly

Poll for ended interviews — do not reverse-copy a "starting soon" window

timeMin is an exclusive lower bound on an event's end time; timeMax is an exclusive upper bound on its start time. A "starting soon" poller (timeMin=now, timeMax=now+30min) works because that pair already means "still ongoing or about to start." Reversing the same shape to timeMin=now−15min&timeMax=now is not enough for "ended": it still returns any event whose end is after 15 minutes ago and whose start is before now — including a two-hour onsite that started 20 minutes ago and has not finished. After every fetch, keep only events where end.dateTime <= now; that client-side check is what "ended" actually means. Poll every 5 minutes with singleEvents=true before orderBy=startTime, skip all-day events (they carry a date field instead of dateTime), and optionally keep an exclude list of coordinator emails that should never be surveyed even when their domain matches.

GET https://www.googleapis.com/calendar/v3/calendars/primary/events
  ?timeMin=2026-08-09T13:45:00-04:00
  &timeMax=2026-08-09T14:00:00-04:00
  &singleEvents=true
  &orderBy=startTime
  &maxResults=10
Authorization: Bearer {access_token}

# Window narrows candidates. After the fetch, keep only
# results where end.dateTime <= now — the API alone does not.

Create the app with two Bot Token Scopes

api.slack.com/apps → Create New App → From scratch → OAuth & Permissions → Bot Token Scopes: chat:write and users:read.email. Install to Workspace and copy the xoxb- token. chat.postMessage's channel parameter accepts a Slack user id directly and opens the DM itself, so there's no im:write scope or conversations.open call to add — every message here is a DM, never a channel post.

Resolve each interviewer to a Slack id

users.lookupByEmail on each identified interviewer's company email. An unmatched email — someone who isn't a Slack workspace member, or a mis-typed calendar invite — returns users_not_found; skip that one DM and keep a tally rather than failing the whole run. Slack answers every call, success or failure, with HTTP 200 — check the response body's ok field, not the status code.

Send the DM with the finished Typeform link

The link is built by the workflow itself, not through any merge-tag templating layer: take the base Typeform URL and append the candidate_id and interviewer_slack_id values already resolved in earlier steps as URL parameters, then drop the finished link into the DM text.

{
  "channel": "U024BE7LH",
  "text": "Feedback needed: Lee Okafor interview (Backend Eng — Onsite)",
  "blocks": [
    { "type": "section", "text": { "type": "mrkdwn",
      "text": "Your interview with *Lee Okafor* just wrapped — 2 minutes for feedback while it's fresh:\n<https://acme.typeform.com/to/iF33dB4ck?candidate_id=2a1f7c9e-...&interviewer_slack_id=U024BE7LH|Rate the candidate>" } }
  ]
}

Build the rating form

One Opinion Scale question, "How would you rate this candidate?" (1-5), plus one open-text "Notes" field for the write-up. Give both a stable ref via the question's Settings menu → Block references, so a later reorder of the form doesn't scramble which answer is which.

Add URL parameters for the candidate and interviewer identity

Form editor → Settings → URL parameters (Typeform's current name for what it used to call Hidden Fields) → add candidate_id and interviewer_slack_id. The workflow already knows both values in memory when it builds the DM — the Notion candidate page id and the Slack id just resolved — so it string-concatenates the finished link itself; no merge-tag templating layer is involved. Every submission echoes both values back in the webhook payload's hidden object.

Register and sign the webhook

Form → Connect → Webhooks → Add a webhook → your endpoint → Save, then toggle it on — it defaults to off. The endpoint must answer over https within 30 seconds or Typeform retries and eventually disables it. Set a signing secret and verify the Typeform-Signature header (format sha256=<base64 HMAC-SHA256 of the raw body>) — the endpoint is public and will get probed.

(Optional) Personal Access Token for a reconciliation pull

Not required for the core flow, which is webhook-driven. If you add a periodic pull to catch missed webhook deliveries, create the token at Account → Personal tokens → Generate a new token, scoped to responses:read only — narrower than granting webhooks:write, which this setup doesn't need since the webhook itself was registered through the UI above, not the API.

Read the payload by ref and by name

The webhook fires form_response with the rating and notes tagged by the refs set above, and the two identity values in the hidden object, tagged by name.

{
  "event_id": "01JXQIFEEDBACK2",
  "event_type": "form_response",
  "form_response": {
    "form_id": "iF33dB4ck",
    "token": "b7c94fd12e",
    "submitted_at": "2026-08-09T15:10:44Z",
    "hidden": { "candidate_id": "2a1f7c9e-...", "interviewer_slack_id": "U024BE7LH" },
    "definition": {
      "fields": [{ "id": "rate01", "type": "opinion_scale", "ref": "candidate_rating" }]
    },
    "answers": [
      { "type": "number", "number": 4, "field": { "ref": "candidate_rating" } },
      { "type": "text", "text": "Strong on system design, light on communication.", "field": { "ref": "feedback_notes" } }
    ]
  }
}

Reuse the Candidates database — or create a lean standalone one

Prefer the same Candidates database your hiring pipeline already keeps (Name, Email, Role, Stage, Source, Résumé, Applied On, Screen Booked, Panel, Notes). Add one property this workflow needs: Interview Feedback (Text). Do not fork a second candidate database for the same people — one person should have one row. No pipeline database yet? Create a lean standalone Candidates table with Name (Title), Email (Email), and Interview Feedback (Text); that path is fully self-contained. Create the connection at app.notion.com/developers/connections if you don't already have one, then open the database → ••• → Connections → Add connection. Grant both Read content and Update content — this workflow matches by email and appends feedback, so a read-only grant is not enough.

Match the candidate by Email

Query with POST /v1/data_sources/{data_source_id}/query (Notion-Version: 2026-03-11; retrieve the database once for its data source id). Filter on the Email property using the external-domain attendee from the calendar event. The returned page id becomes the Typeform candidate_id URL parameter — resolve to an internal id once, then thread it through.

{
  "filter": { "property": "Email", "email": { "equals": "lee@northwind.co" } },
  "page_size": 1
}

Append feedback — never overwrite

PATCH replaces a rich_text property's value wholesale — it does not append. First GET the page to read the current Interview Feedback value, then PATCH with that text plus one new line added, per submission. Skipping the read-before-write matters here specifically: several interviewers submit for the same candidate close together, and a blind PATCH from a later submission can silently drop an earlier one's feedback.

{
  "properties": {
    "Interview Feedback": {
      "rich_text": [
        // content below is AFTER concatenating prior Interview Feedback + the new line
        { "type": "text", "text": { "content": "2026-08-09 — Rae Okafor rated 4/5: Strong on system design, light on communication.\n" } }
      ]
    }
  }
}