Copy page

Advanced Topics

Webhooks

Webhooks deliver platform events to your app's own backend — HTTP POSTs signed with your app's secret, fired whenever something the app cares about happens on the platform. Complements Realtime Channels: realtime pushes events into your app's SDK view while a learner is active; webhooks reach your server even when no learner is online.

What you can build

• Data sync — mirror course completions, quiz submissions, or member joins into an HR system, LMS, analytics warehouse, or CRM.
• Backend integrations — post activity notifications to Slack, Discord, Microsoft Teams, or a shared inbox.
• Provisioning + teardown — bootstrap per-tenant state when your app is installed on a new organization; clean up when it's uninstalled.
• Third-party mirroring — keep a system-of-record (e.g. a marketing tool or student-info system) in step with events happening on the platform.

How it works

Every extension app can optionally declare a single webhook endpoint URL in its manifest. When an organization installs the app, Teachfloor auto-provisions the delivery pipeline against that URL — no per-tenant configuration required. The app's backend receives POSTs for every event it subscribed to, plus two lifecycle events (app.installed, app.uninstalled) that fire regardless of subscription.

One URL per app is delivered to for every installing organization. The payload carries the organization identifier so your backend can attribute the event to the right tenant.

Manifest schema

Declare the block at the top level of your manifest alongside views and permissions:

Code
{
  "id": "my-app",
  "name": "My App",
  "version": "1.0.0",
  "webhook": {
    "url": "https://my-app.com/teachfloor/webhook",
    "events": [
      "course.completed",
      "element.completed",
      "course.join"
    ]
  }
}

Fields:

Field	Required	Rules
webhook.url	yes (when block present)	https:// only. HTTP is rejected — signed payloads over plaintext give no meaningful integrity guarantee. Max 2048 chars.
webhook.events	no	Array of event names drawn from the event catalog. Empty array is valid — you still receive the lifecycle events. Unknown event names are rejected at manifest push time.

Omit the block entirely if your app doesn't need backend deliveries.

The signing secret

Every app has a single master signing secret used to sign every webhook delivery to your endpoint, across every installing organization. You manage one secret per app, not one per install.

Where to find it: Developers → Apps → your app → the header metadata strip includes a "Signing Secret" cell with a reveal button. Click to show the raw value.

The secret is generated automatically when your app is created.

Signature verification

Every delivery includes a Teachfloor-Signature header. The signature is HMAC-SHA256(secret, request_body). Verify it before trusting the payload.

Node.js / Express:

Code
const crypto = require('crypto')
const express = require('express')

const app = express()

// Capture the raw body — Express's default JSON middleware discards it.
app.use('/teachfloor/webhook', express.raw({ type: 'application/json' }))

const TEACHFLOOR_SECRET = process.env.TEACHFLOOR_WEBHOOK_SECRET

app.post('/teachfloor/webhook', (req, res) => {
  const signature = req.header('Teachfloor-Signature')
  const expected = crypto
    .createHmac('sha256', TEACHFLOOR_SECRET)
    .update(req.body)
    .digest('hex')

  if (!signature || !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send('invalid signature')
  }

  const event = JSON.parse(req.body.toString())
  console.log('received', event.type, 'for', event.data.organization.id)
  res.status(200).end()
})

Python / Flask:

Code
import hmac
import hashlib
import json
import os
from flask import Flask, request, abort

app = Flask(__name__)
TEACHFLOOR_SECRET = os.environ["TEACHFLOOR_WEBHOOK_SECRET"].encode()

@app.route("/teachfloor/webhook", methods=["POST"])
def webhook():
    signature = request.headers.get("Teachfloor-Signature", "")
    expected = hmac.new(TEACHFLOOR_SECRET, request.data, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(signature, expected):
        abort(401)

    event = json.loads(request.data)
    print(f"received {event['type']} for {event['data']['organization']['id']}")
    return "", 200

PHP:

Code
$secret    = getenv('TEACHFLOOR_WEBHOOK_SECRET');
$body      = file_get_contents('php://input');
$signature = $_SERVER['HTTP_TEACHFLOOR_SIGNATURE'] ?? '';
$expected  = hash_hmac('sha256', $body, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true);
error_log("received {$event['type']} for {$event['data']['organization']['id']}");
http_response_code(200);

Always use a constant-time comparison (timingSafeEqual / hmac.compare_digest / hash_equals). A plain == opens a timing side-channel on the signature check.

Payload shape

Every delivery has the same envelope, with an event-specific data block inside:

Code
{
  "id": "evt_abc123",
  "type": "course.completed",
  "created_at": "2026-07-25T14:32:01.000000Z",
  "installation_id": "7YWJgrMnJMybawx1",
  "data": {
    ...event-specific fields
  }
}

id is stable and unique — safe to use as an idempotency key (and mirrored in the Teachfloor-Idempotency-Key header — see Delivery guarantees). type matches one of the subscribable event names. installation_id is the hashid of the InstalledApp this delivery targets — use it to look up which install fired the event without inspecting the data block (whose shape varies per event type).

Lifecycle events

Two events are always delivered to your endpoint regardless of your events subscription:

app.installed — fired when an organization installs your app.

Code
{
  "id": "evt_...",
  "type": "app.installed",
  "created_at": "2026-07-25T14:32:01.000000Z",
  "installation_id": "7YWJgrMnJMybawx1",
  "data": {
    "organization": {
      "id": "acme-corp",
      "name": "Acme Corp"
    },
    "app": {
      "id": "6a41091c53b30",
      "name": "My App",
      "version": "1.0.0"
    },
    "installer": {
      "id": "usr_abc123",
      "email": "alice@acme.com",
      "full_name": "Alice Doe"
    },
    "credentials": {
      "client_id": "9f8e7d6c-...",
      "access_token": "eyJhbGc...",
      "refresh_token": "def50200...",
      "expires_at": "2026-08-25T14:32:01+00:00",
      "token_type": "Bearer",
      "scope": "courses:read modules:read"
    }
  }
}

The installer block identifies the user who clicked Install — always present on app.installed, regardless of whether the app declares any additional integrations. Use it to auto-provision or match an account on your landing page before the user arrives, so the post-install redirect can drop them straight into a signed-in experience rather than a sign-up form.

installer fields:

• id — the installer's user hashid; same format the SDK surfaces elsewhere.
• email — key your account lookup on this.
• full_name — for greetings / display.

The credentials block is opt-in and only appears when both of these are true in the app manifest:

1. An explicit oauth: { type: "install" } block declares that the app wants install-integrated OAuth.
2. At least one declared permission maps to an OAuth scope (currently: courses:read, modules:read, elements:read, members:read, activities:read).

See the OAuth chapter for the full end-to-end recipe — opt-in, storage shape, calling the API, refresh flow, and code samples in Node / Python / PHP.

Code
{
  "id": "my-app",
  "oauth": { "type": "install" },
  "permissions": [
    { "permission": "courses:read", "purpose": "Sync course completions to our HR tool" }
  ],
  "webhook": { "url": "https://…", "events": ["course.completed"] }
}

Without the oauth block, no tokens are minted even if the manifest declares OAuth-mappable permissions — an SDK-only app that adds courses:read for in-app use won't unexpectedly start receiving credentials in its webhook receiver logs. Adding oauth: { type: "install" } is the explicit opt-in.

SDK-only apps and apps with only SDK-scoped storage permissions receive no credentials — they can still deliver a signed webhook, they just don't get an access token for the public API. When credentials is present, use the tokens to call the public API on behalf of the installing organization — bearer-authenticated with access_token, refreshable via the standard OAuth 2.0 /oauth/token refresh flow using client_id + client_secret + refresh_token. Store access_token and refresh_token per-install (keyed by organization.id).

The client_secret is not in the webhook payload — you fetch it once from the Teachfloor developer dashboard (Developers → Apps → your app → OAuth Client Secret) or from the teachfloor apps create CLI response, and store it in your app config. It's the same across every install of your app.

credentials fields:

• client_id — the app's OAuth client identifier. Same across every install; not sensitive. Delivered here for correlation.
• access_token — bearer token for public API calls. Expires per expires_at.
• refresh_token — POST to /oauth/token with grant_type=refresh_token to mint a new access token; refresh tokens rotate (the old one is invalidated).
• expires_at — ISO 8601 timestamp for the access token; refresh before this.
• token_type — always Bearer.
• scope — space-separated scopes granted to this token.

app.uninstalled — fired just before an organization uninstalls your app.

Same payload shape as app.installed minus the installer block. app.version reflects the version being uninstalled (relevant during upgrades — see below). Use this event to purge tenant state.

Version upgrades

When an organization upgrades your app to a new version, the platform tears down the old install and creates a new one. Your backend receives, in order:

1. app.uninstalled for the old version (fired against the old endpoint URL if that changed between versions).
2. app.installed for the new version (fired against the new endpoint URL).

Design your handlers to be idempotent. The envelope-level installation_id changes between the old and new install; correlate by organization.id if you need to detect an upgrade rather than a fresh install.

If the new manifest drops the webhook block, only app.uninstalled fires — the app.installed event has nowhere to go. Treat the app.uninstalled as your last signal from that org.

Event catalog

You can subscribe to any of the following:

Event	Fires when
course.created	A course is created in the org
course.updated	Course metadata changes
course.completed	A learner marks a course as completed
course.join	A learner joins a course
module.created	A module is added to a course
module.updated	Module metadata changes
element.created	An element is added to a module
element.updated	Element metadata changes
element.deleted	An element is removed
element.completed	A learner completes an element
member.login	A member logs into the org
app.installed	(always delivered)
app.uninstalled	(always delivered)

Subscribing to an unknown event name is rejected at manifest push time.

Delivery guarantees

• Retry — up to 3 attempts on any non-2xx response, with exponential backoff between attempts.
• Timeout — 10 seconds per attempt. Endpoints that take longer are considered failed and retried. If you need to do more work than 10 seconds allows, respond 2xx immediately and enqueue the work.
• Order — deliveries are queued and processed asynchronously. Events for the same organization may be delivered out of order if one takes multiple attempts to succeed. Use the envelope's created_at if strict ordering matters.
• At-least-once — a single event may be delivered more than once if your endpoint responds 200 after our timeout window. Dedupe on the Teachfloor-Idempotency-Key header (equivalent to the envelope id) — the header is stable across retry attempts, so it lets you short-circuit duplicate work before parsing the body.
• HTTPS required — HTTP endpoints are rejected at manifest validation. TLS 1.2+ is expected on your endpoint.

Respond with any 2xx status code to acknowledge receipt. Any other response (4xx, 5xx, timeout) triggers a retry.

Security model

• Signature verification is your responsibility. A delivery that doesn't verify against your master secret is forged — reject it.
• The delivery URL and secret cross the wire only over HTTPS, both from admin to browser (when revealing the secret) and from Teachfloor to your endpoint.
• No inbound path is opened by declaring webhooks. Webhooks are strictly outbound — Teachfloor never calls into your app's SDK view or your platform-side runtime as a result of a webhook declaration.
• Uninstall removes the endpoint. When an org uninstalls your app, the webhook endpoint row is deleted (after the final app.uninstalled delivery). Further platform events do not attempt to reach your endpoint for that org.

Next Steps

→ Continue to OAuth

Additional Resources

• Realtime Channels - Sub-second event delivery into your app's SDK view while the learner is active. Complementary to webhooks (which reach your backend regardless).
• Permissions - The permission scopes your app can declare in its manifest.
• App Manifest - The full manifest schema, including the webhook block.