Webhooks

Receive real-time notifications when events happen on the TimeBack Platform. Instead of polling APIs, register a webhook subscription and the platform will POST a signed JSON payload to your HTTPS endpoint within seconds of the event.

Quick Start

1. Register your App — see Level 0: Register Your App. You receive your App ID and OAuth credentials in the response.
2. Authenticate — exchange your credentials for an access token using the OAuth client credentials flow.
3. Create a webhook subscription — POST /webhooks/1.0/{sourcedApplicationId}/subscriptions with your consumer URL and the event types you want.
4. Store the signing secret — the response includes a signingSecret (prefixed whsec_). This is shown exactly once. Store it in your secrets manager immediately.
5. Implement your consumer endpoint — an HTTPS endpoint that verifies the signature and returns 2xx within 10 seconds.
6. Go live — the platform starts delivering matching events to your endpoint within seconds of occurrence.

Prerequisites

• A registered App with an App ID (see Level 0: Register Your App)
• OAuth credentials (clientId + clientSecret) from registration (see Authentication)
• An HTTPS endpoint reachable from the public internet (HTTP is rejected, raw IP addresses are rejected — use a domain name)

Concepts

Subscriptions

A subscription tells the platform where to deliver events and which event types to include. Each subscription belongs to one App and has:

Event Types

Each event type is a dot-separated string describing what happened (e.g., insight.created, user_profile.updated). Event types are registered by platform modules as they ship — your subscription only receives events matching the types you listed.

Available event types are listed in the Event Types Reference section below. The engine is live; production event types will be added incrementally as platform modules integrate with it.

Thin Payloads

Webhook payloads contain entity references only, not full entity data. This keeps payloads small, avoids stale-data issues, and respects access control — your consumer fetches the current state from the standard REST APIs using its own credentials and scopes.

For example, an insight.created event would include the insight ID and student ID, but not the insight text or student profile. Your consumer calls GET /insights/... with its own token to retrieve the full data.

Authentication for Webhook Management

Webhook management endpoints use the same OAuth 2.0 authentication as all other TimeBack Platform APIs. You need a valid access token obtained via the client credentials flow.

The webhook management endpoints are scoped by App ownership — your token must belong to the same App (auth client) that owns the subscription. In addition, the calling user must hold the app:manage_webhooks permission grant on urn:app:{sourcedApplicationId}. This grant is issued automatically to the App owner at registration time.

Note: Webhook management (creating/updating subscriptions) uses OAuth tokens. Webhook deliveries (the POST requests to your endpoint) are authenticated differently — via HMAC-SHA256 signatures, not OAuth. See Verifying Signatures below.

Subscription Management

Create a Subscription

POST /webhooks/1.0/{sourcedApplicationId}/subscriptions

Request body:

{
  "url": "https://your-service.example.com/webhooks",
  "eventTypes": ["insight.created"]
}

Response (201):

{
  "id": "eee11b2d-66db-4ed0-85c4-3438eccf733f",
  "url": "https://your-service.example.com/webhooks",
  "eventTypes": ["insight.created"],
  "status": "active",
  "dateCreated": "2026-06-13T08:37:30.542Z",
  "signingSecret": "whsec_123a4ae3aa67fc9ed203aef225f8ee9abc28f43b..."
}

Important: The signingSecret is only returned at creation time and when you explicitly rotate it. It is never included in list or get responses. Store it immediately — if you lose it, rotate via the rotate-secret endpoint.

Validation rules:

• url must be a valid HTTPS URL with a domain name (HTTP is rejected with 400, raw IP addresses like https://1.2.3.4/hook are rejected with 400).
• eventTypes must contain at least one entry, and every entry must be a recognized event type (see Event Types Reference). Unknown types are rejected with 400.

List Subscriptions

GET /webhooks/1.0/{sourcedApplicationId}/subscriptions

Response (200):

[
  {
    "id": "eee11b2d-66db-4ed0-85c4-3438eccf733f",
    "url": "https://your-service.example.com/webhooks",
    "eventTypes": ["insight.created"],
    "status": "active",
    "dateCreated": "2026-06-13T08:37:30.542Z"
  }
]

Returns all subscriptions for the App. The signing secret is never included.

Get a Subscription

GET /webhooks/1.0/{sourcedApplicationId}/subscriptions/{subscriptionId}

Returns a single subscription. The signing secret is never included.

Update a Subscription

PUT /webhooks/1.0/{sourcedApplicationId}/subscriptions/{subscriptionId}

Request body (all fields optional — include only what you want to change):

{
  "url": "https://new-endpoint.example.com/webhooks",
  "eventTypes": ["insight.created", "user_profile.updated"],
  "status": "paused"
}

Status transitions:

You cannot set status to disabled — that state is reserved for platform auto-disable after repeated delivery failures.

Paused vs Disabled: paused is a lossless pause — events accumulate and are delivered when you resume. disabled is a hard stop — events that occur while disabled are dropped. Use paused for planned maintenance windows; disabled is set automatically by the platform after terminal delivery failures.

Delete a Subscription

DELETE /webhooks/1.0/{sourcedApplicationId}/subscriptions/{subscriptionId}

Response: 204 No Content

Soft-deletes the subscription. No further deliveries are attempted. This action is not reversible — create a new subscription if you need to resume.

Rotate the Signing Secret

POST /webhooks/1.0/{sourcedApplicationId}/subscriptions/{subscriptionId}/rotate-secret

Response (200):

{
  "id": "eee11b2d-66db-4ed0-85c4-3438eccf733f",
  "url": "https://your-service.example.com/webhooks",
  "eventTypes": ["insight.created"],
  "status": "active",
  "dateCreated": "2026-06-13T08:37:30.542Z",
  "signingSecret": "whsec_newrotatedsecret..."
}

Generates a new signing secret and returns it. During the rotation window, both the old and new secrets are valid — in-flight deliveries signed with the previous secret still verify. Update your consumer to use the new secret as soon as possible.

When to rotate:

• Your secret may have been exposed (e.g., committed to a public repo).
• Your security policy requires periodic rotation.
• You lost the original secret and need a new one.

Delivery Format

When an event matches your subscription, the platform sends an HTTPS POST to your url with the following:

Headers

Body (Envelope)

{
  "id": "fec49ed7-2130-493b-95d6-089e91ffd92e",
  "type": "insight.created",
  "timestamp": "2026-06-13T08:42:09.204Z",
  "data": {
    "insightId": "abc123",
    "studentId": "def456"
  }
}

Verifying Signatures

Every delivery is signed with your subscription's signingSecret using HMAC-SHA256. Always verify signatures before processing a delivery — this confirms the request came from TimeBack and hasn't been tampered with.

Algorithm

1. Extract the X-TimeBack-Webhook-Timestamp header value.
2. Read the raw request body as a UTF-8 string (before JSON parsing).
3. Concatenate: {timestamp}.{body} (the timestamp, a literal dot, then the raw body).
4. Compute HMAC-SHA256 using your signingSecret as the key and the concatenated string as the message.
5. Hex-encode the result.
6. Compare the computed hex string against the X-TimeBack-Webhook-Signature header using a constant-time comparison function to prevent timing attacks.
7. (Recommended) Reject deliveries whose timestamp is more than 5 minutes old (300 seconds) to prevent replay attacks.

Node.js Example

import { createHmac, timingSafeEqual } from 'crypto';

function verifyWebhookSignature(secret, timestamp, body, signature) {
  const payload = `${timestamp}.${body}`;
  const expected = createHmac('sha256', secret).update(payload).digest('hex');

  const expectedBuf = Buffer.from(expected, 'utf-8');
  const signatureBuf = Buffer.from(signature, 'utf-8');

  if (expectedBuf.length !== signatureBuf.length) return false;
  return timingSafeEqual(expectedBuf, signatureBuf);
}

// Express.js handler example:
app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.headers['x-timeback-webhook-timestamp'];
  const signature = req.headers['x-timeback-webhook-signature'];
  const body = req.body.toString('utf-8');

  // 1. Verify signature
  if (!verifyWebhookSignature(process.env.WEBHOOK_SECRET, timestamp, body, signature)) {
    return res.status(401).send('Invalid signature');
  }

  // 2. Reject stale deliveries (replay protection)
  const ageSeconds = Math.floor(Date.now() / 1000) - parseInt(timestamp, 10);
  if (ageSeconds > 300) {
    return res.status(401).send('Timestamp too old');
  }

  // 3. Parse and process
  const event = JSON.parse(body);
  console.log(`Received ${event.type} event: ${event.id}`);

  // 4. Deduplicate — check if you've already processed this event.id
  // ...your deduplication logic here...

  // 5. Respond 200 immediately, process asynchronously if needed
  res.status(200).send('OK');
});

Gotcha: Use express.raw() (not express.json()) to get the raw body bytes. If Express parses JSON first, the re-serialized body may differ from the original (key order, whitespace) and the signature won't match.

Python (Flask) Example

import hashlib
import hmac
import json
import time
from flask import Flask, request

app = Flask(__name__)

def verify_webhook(secret: str, timestamp: str, body: str, signature: str) -> bool:
    payload = f"{timestamp}.{body}"
    expected = hmac.new(
        secret.encode(), payload.encode(), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

@app.route('/webhooks', methods=['POST'])
def handle_webhook():
    timestamp = request.headers.get('X-TimeBack-Webhook-Timestamp', '')
    signature = request.headers.get('X-TimeBack-Webhook-Signature', '')
    body = request.get_data(as_text=True)

    if not verify_webhook(WEBHOOK_SECRET, timestamp, body, signature):
        return 'Invalid signature', 401

    if time.time() - int(timestamp) > 300:
        return 'Timestamp too old', 401

    event = json.loads(body)
    print(f"Received {event['type']} event: {event['id']}")

    # Deduplicate by event['id'] and process...

    return 'OK', 200

Consumer Requirements

Your webhook consumer endpoint must satisfy all of the following:

Retry & Failure Behavior

Recovering from Auto-disable

If your subscription is auto-disabled after exhausting retries:

1. Diagnose and fix your endpoint (check logs, DNS, TLS certificate, firewall rules).
2. Re-enable the subscription: PUT /webhooks/1.0/{sourcedApplicationId}/subscriptions/{subscriptionId} with {"status": "active"}.
3. Catch up on missed events. Events that occurred while the subscription was disabled are not retroactively delivered. Use the relevant REST APIs to poll for data you may have missed.

Why 4xx Is Terminal

Unlike 5xx (which indicates a transient server error), 4xx responses indicate a client-side issue — the consumer explicitly rejected the payload. Retrying the same payload to an endpoint that already returned 4xx wastes resources for both sides. Common causes:

• 401 — your signature verification is rejecting valid signatures (check your secret).
• 404 — your endpoint URL changed but the subscription wasn't updated.
• 400 — your consumer has validation that rejects the payload shape.

If you receive unexpected 4xx rejections, check your consumer logs and update your subscription URL or signing secret as needed.

End-to-End Example

Here's the complete flow from subscription creation to processing a delivery:

Step 1 — Create the subscription (your backend, at setup time):

curl -X POST https://platform.timeback.com/webhooks/1.0/{sourcedApplicationId}/subscriptions \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-service.example.com/webhooks",
    "eventTypes": ["insight.created"]
  }'

Save signingSecret from the response to your secrets manager.

Step 2 — Platform delivers an event (automatic, when an insight is created):

POST /webhooks HTTP/1.1
Host: your-service.example.com
Content-Type: application/json
X-TimeBack-Webhook-Timestamp: 1718267529
X-TimeBack-Webhook-Signature: a1b2c3d4e5f6...

{
  "id": "fec49ed7-2130-493b-95d6-089e91ffd92e",
  "type": "insight.created",
  "timestamp": "2026-06-13T08:42:09.204Z",
  "data": {
    "insightId": "abc123",
    "studentId": "def456"
  }
}

Step 3 — Your consumer processes the delivery:

1. Verify the HMAC-SHA256 signature using your stored signingSecret.
2. Check the timestamp is within 5 minutes.
3. Deduplicate by id (check your database or cache).
4. Return 200 OK immediately.
5. Asynchronously: fetch the full insight data via GET /insights/... with your own OAuth token, and act on it.

Troubleshooting

"Unknown webhook event type(s)" when creating a subscription

The eventTypes you specified aren't recognized by the platform. Check the Event Types Reference for the current list. Event types are added incrementally as platform modules integrate with the webhook engine.

Signature verification fails on your consumer

• Ensure you're verifying against the raw request body string, not a re-serialized version. JSON parsers may reorder keys or alter whitespace, which changes the signature.
• Confirm your stored secret matches the one returned at subscription creation (or last rotation). Secrets start with whsec_.
• Check that you're concatenating as {timestamp}.{body} (with a literal . between them).

Subscription was auto-disabled

Your endpoint failed to return 2xx for approximately 24 hours (96 retry attempts). See Recovering from Auto-disable.

Not receiving deliveries

• Verify the subscription status is active (not paused or disabled).
• Confirm the events being emitted match one of the eventTypes in your subscription.
• Ensure your endpoint is publicly reachable from AWS us-east-1 (test with a curl from an EC2 instance or similar).
• Check that your endpoint returns 2xx — 4xx responses mark deliveries as terminal without retry.

Lost your signing secret

Rotate the secret: POST /webhooks/1.0/{sourcedApplicationId}/subscriptions/{subscriptionId}/rotate-secret. The new secret is returned in the response. Update your consumer immediately.

Event Types Reference

Event types are added as platform modules integrate with the webhook engine. Each event type documents its data shape so you know what entity references to expect.

Additional event types for insights, user profiles, and other platform domains will be documented here as they ship. Subscribe to specific types — your subscription is not affected when new types are added to the platform.

Related Docs

Level 0: Register Your App

Register your App to get an App ID and OAuth credentials — the prerequisite for creating webhook subscriptions.

Authentication

Exchange your OAuth credentials for access tokens to call the webhook management endpoints.

App Lifecycle

Understand draft vs active tiers and how they affect your App's capabilities, including webhook subscriptions.

API Reference

Interactive API reference with full request/response schemas for all webhook endpoints.