schedule interviews api webhook reminders

Here’s a practical way to set up interview scheduling with API + webhooks + reminders.

Recommended architecture

1. Client schedules an interview

   • Your app calls your backend API:
     • POST /interviews
   • Backend stores the interview in your database.

2. Backend triggers notifications

   • On create/update/cancel, backend emits events:
     • interview.scheduled
     • interview.rescheduled
     • interview.cancelled

3. Webhook delivery

   • Your system sends webhook requests to subscribed endpoints:
     • Event payload includes interview details, candidate, interviewer, time, timezone, location, meeting link, etc.
   • Add retries, signing, and idempotency.

4. Reminders

   • Use a job queue / scheduler to send reminders at set times:
     • 24 hours before
     • 1 hour before
     • 10 minutes before
   • Reminders can be sent via email/SMS/push/webhook.

---

Example API flow

Create interview

POST /interviews

{
  "candidate_id": "cand_123",
  "interviewer_id": "int_456",
  "starts_at": "2026-10-16T14:00:00Z",
  "ends_at": "2026-10-16T14:30:00Z",
  "timezone": "UTC",
  "location": "Google Meet",
  "meeting_url": "https://meet.example.com/abc"
}

Response

{
  "id": "iv_789",
  "status": "scheduled",
  "starts_at": "2026-10-16T14:00:00Z"
}

---

Webhook event example

POST https://client-app.com/webhooks/interviews

Headers:

X-Webhook-Event: interview.scheduled
X-Webhook-Signature: t=...,v1=...

Payload:

{
  "event": "interview.scheduled",
  "data": {
    "id": "iv_789",
    "candidate_id": "cand_123",
    "interviewer_id": "int_456",
    "starts_at": "2026-10-16T14:00:00Z",
    "ends_at": "2026-10-16T14:30:00Z",
    "timezone": "UTC",
    "meeting_url": "https://meet.example.com/abc"
  },
  "created_at": "2026-10-15T10:00:00Z"
}

---

Reminder scheduling

When an interview is created, enqueue reminder jobs:

• reminder_24h
• reminder_1h
• reminder_10m

Reminder payload

{
  "interview_id": "iv_789",
  "type": "reminder_1h",
  "send_at": "2026-10-16T13:00:00Z"
}

---

Good practices

• Timezone-aware scheduling: always store UTC + user timezone.
• Webhook signing: HMAC signature to verify authenticity.
• Retries with backoff: for failed webhook deliveries.
• Idempotency keys: avoid duplicate processing.
• Status tracking: scheduled / completed / cancelled / no-show.
• Audit log: record event deliveries and reminder sends.

---

If you want, I can also give you:

1. a database schema
2. a Node.js/Express implementation
3. a FastAPI implementation
4. a webhook receiver + retry worker
5. a full OpenAPI spec

If you tell me your stack, I can draft the exact API.