技能 编程开发 MindTickle网络钩子与事件处理

MindTickle网络钩子与事件处理

v20260423
mindtickle-webhooks-events
本技能提供MindTickle网络钩子(Webhook)的完整指南和实现方法。它允许外部系统实时响应MindTickle平台上的关键用户生命周期事件,如课程完成、测验提交、用户开通/停用和进度更新。可用于将学习进度同步到CRM或HRIS,或自动化用户访问管理。
获取技能
364 次下载
概览

MindTickle Webhooks & Events

Overview

MindTickle emits webhook events as sales reps progress through enablement programs, complete courses, submit quizzes, and are provisioned or deprovisioned from the platform. These events enable integrations such as pushing completion certificates to an LMS, syncing learner progress to Salesforce rep profiles, triggering manager alerts when quiz scores fall below threshold, and automating user lifecycle management with your IdP. All payloads are HMAC-signed JSON scoped to your company, delivered over HTTPS.

Prerequisites

  • MindTickle admin access with API & Webhooks permissions enabled
  • Webhook endpoint URL accessible over HTTPS (TLS 1.2+)
  • Company-scoped signing secret from MindTickle Admin > Integrations (MINDTICKLE_WEBHOOK_SECRET)
  • Express.js with raw body parsing for HMAC verification

Webhook Registration

import axios from "axios";

const res = await axios.post(
  "https://api.mindtickle.com/v2/webhooks",
  {
    url: "https://your-app.com/webhooks/mindtickle",
    events: ["course.completed", "quiz.submitted", "user.provisioned",
             "user.deprovisioned", "module.progress"],
    companyId: process.env.MINDTICKLE_COMPANY_ID,
  },
  { headers: { Authorization: `Bearer ${process.env.MINDTICKLE_API_TOKEN}`,
               "Content-Type": "application/json" } }
);
console.log("Webhook ID:", res.data.webhookId);

Signature Verification

import crypto from "crypto";
import { Request, Response, NextFunction } from "express";

function verifyMindTickleSignature(req: Request, res: Response, next: NextFunction) {
  const signature = req.headers["x-mt-webhook-signature"] as string;
  const timestamp = req.headers["x-mt-webhook-timestamp"] as string;
  if (!signature || !timestamp) return res.status(401).send("Missing signature");

  const signedPayload = `${timestamp}:${(req as any).rawBody}`;
  const expected = crypto
    .createHmac("sha256", process.env.MINDTICKLE_WEBHOOK_SECRET!)
    .update(signedPayload)
    .digest("hex");

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(403).send("Invalid signature");
  }
  next();
}

Event Handler

app.post("/webhooks/mindtickle", verifyMindTickleSignature, (req, res) => {
  const { event, data, companyId } = req.body;

  switch (event) {
    case "course.completed":
      console.log(`${data.userId} completed "${data.courseName}" — score: ${data.score}%`);
      break;
    case "quiz.submitted":
      console.log(`Quiz "${data.quizName}" by ${data.userId}: ${data.score}/${data.maxScore}`);
      break;
    case "user.provisioned":
      console.log(`User provisioned: ${data.email}, role: ${data.role}, team: ${data.teamId}`);
      break;
    case "user.deprovisioned":
      console.log(`User removed: ${data.userId}, reason: ${data.reason}`);
      break;
    case "module.progress":
      console.log(`${data.userId} at ${data.progressPct}% in module "${data.moduleName}"`);
      break;
    default:
      console.warn(`Unhandled event: ${event}`);
  }
  res.status(200).json({ received: true });
});

Event Types

EventPayload FieldsUse Case
course.completeduserId, courseName, courseId, score, completedAtPush certificates to LMS or update Salesforce training status
quiz.submitteduserId, quizName, quizId, score, maxScore, passedFlag low-scoring reps for coaching follow-up
user.provisioneduserId, email, role, teamId, provisionedBySync new hires to enablement programs automatically
user.deprovisioneduserId, email, reason, deprovisionedAtRevoke access in downstream systems and archive data
module.progressuserId, moduleName, moduleId, progressPct, timeSpentSecBuild real-time leaderboards and progress dashboards
certification.expireduserId, certName, expiredAt, renewalDeadlineTrigger re-certification workflow in IdP

Retry & Idempotency

const processed = new Set<string>();

function ensureIdempotent(req: Request, res: Response, next: NextFunction) {
  const eventId = req.headers["x-mt-event-id"] as string;
  if (processed.has(eventId)) {
    return res.status(200).json({ duplicate: true });
  }
  processed.add(eventId);
  next();
}
// MindTickle retries up to 4 times with linear backoff (5 min, 15 min, 60 min, 6 hours).
// After 24 hours of failures, the webhook is suspended and an admin email is sent.

Error Handling

IssueCauseFix
401 on all deliveriesCompany-scoped secret rotated by adminRe-copy secret from Admin > Integrations and redeploy
user.provisioned not firingWebhook not subscribed to SCIM eventsAdd user.provisioned to the events array in subscription
Duplicate course.completedLearner retook course, triggered redeliveryDeduplicate on x-mt-event-id header
Payload missing score fieldQuiz configured as ungraded practiceCheck data.quizType — practice quizzes omit scoring fields
Webhook suspendedEndpoint down for 24+ hoursFix endpoint, then re-activate via PATCH /v2/webhooks/{id}

Resources

Next Steps

See mindtickle-security-basics.

信息
分类 编程开发
名称 mindtickle-webhooks-events
版本 v20260423
大小 5.59KB
更新时间 2026-04-28
语言