Webhooks

Thrive can notify your systems in real-time when key events occur on the platform. When a matching event fires, Thrive sends an HTTP POST request containing a JSON payload to the URL you have configured for that subscription type.

Implementation will handle the configuration setup alongside you.

Subscription Types

Webhooks are grouped into six subscription types. Each subscription type has its own URL configuration and delivers a distinct set of events.

Common Payload Fields

Every event payload includes the following top-level fields regardless of event type.

Setting Up Your Webhooks

You configure webhooks yourself by sending a short request to Thrive for each subscription type you want to receive. Each subscription has its own configuration that tells Thrive where to send events (a URL) and, optionally:

• a secret used to sign requests with HMAC so you can verify they came from Thrive (see Verifying the HMAC Signature)
• OAuth 2.0 client credentials so Thrive obtains a bearer token from your identity provider and sends it on each delivery (see OAuth 2.0 Authentication)

HMAC and OAuth are independent — you can use either, both, or neither.

There are six subscription types (see Subscription Types above), so you can set up to configurations. If you want to receive everything at a single endpoint, simply use the same URL in all six.

Step 1 - Get your credentials

Configuration requires administrator access. Follow Step 1 of the Authentication guide to copy two values from your browser while signed in as an admin:

• your Authorization header (the value beginning with Bearer)
• your Correlation-Id header

You'll send these with each configuration request in Step 3.

Step 2 - Choose your environment

Send your configuration request to the endpoint for the environment you're setting up:

Requests are sent as an HTTP POST with your credentials from Step 1 in the request headers.

Step 3 - Send a configuration for each subscription

For each subscription type you want to enable, send the following GraphQL mutation. Set key to the subscription type and value to a JSON string containing your url (and optionally secret and/or auth):

HMAC only (optional secret):

mutation {
  setSecureConfig(
    input: {
      category: "webhooks"
      key: "content_subscription"
      value: "{\"url\":\"https://example.com/webhooks\",\"secret\":\"your-secret\"}"
    }
  ) {
    isSet
  }
}

OAuth 2.0 client credentials:

mutation {
  setSecureConfig(
    input: {
      category: "webhooks"
      key: "content_subscription"
      value: "{\"url\":\"https://example.com/webhooks\",\"auth\":{\"type\":\"oauth2\",\"tokenUrl\":\"https://auth.example.com/oauth/token\",\"clientId\":\"your-client-id\",\"clientSecret\":\"your-client-secret\",\"grantType\":\"client_credentials\"}}"
    }
  ) {
    isSet
  }
}

You can include both secret and auth in the same value if you want HMAC signing and a bearer token on each request.

• key - the subscription type. One of: completion_subscription, content_subscription, assignment_subscription, notification_subscription, user_subscription, event_subscription.
• value - a JSON string (with quotes escaped, as shown) containing:
  • url (required) - the HTTPS endpoint Thrive should send events to. Must be publicly reachable and use https://.
  • secret (optional) - a secret used to sign each request. If you provide one, Thrive adds an x-hmac-signature header you can verify (see Verifying the HMAC Signature). Omit it if you don't need signature verification: value: "{\"url\":\"https://example.com/webhooks\"}"
  • auth (optional) - OAuth 2.0 settings. When present with type: "oauth2", Thrive fetches an access token from your tokenUrl and sends Authorization: Bearer <access_token> on each delivery (see OAuth 2.0 Authentication).

If you'd rather use the command line, an HMAC example looks like this:

curl https://tenant.api.learn.link/config \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -H "Correlation-Id: YOUR_CORRELATION_ID" \
  -d '{"query":"mutation { setSecureConfig(input: { category: \"webhooks\", key: \"content_subscription\", value: \"{\\\"url\\\":\\\"https://example.com/webhooks\\\",\\\"secret\\\":\\\"your-secret\\\"}\" }) { isSet } }"}'

A successful response returns:

{ "data": { "setSecureConfig": { "isSet": true } } }

Note: isSet confirms your configuration was saved. If you re-send the exact same value a second time, isSet returns false because nothing changed, your configuration is still in place.

Step 4 - Repeat for each subscription

Repeat Step 3 for each subscription type you want to receive, changing the key (and the url if you're using different endpoints). To send every event to one endpoint, use the same url in all six configurations.

To update a webhook later, send the mutation again with the new value. Changes can take up to 15 minutes to take effect.

HTTP Request Details

Every webhook request is sent as:

• Method: POST
• Content-Type: application/json
• Body: JSON-encoded event payload
• Optional headers (depending on config):
  • x-hmac-signature: sha256=<hex-digest> when a secret is configured
  • Authorization: Bearer <access_token> when OAuth 2.0 (auth.type: "oauth2") is configured

Your endpoint must respond with a 2xx status code within 30 seconds. If the request times out or returns a non-2xx response, Thrive will retry delivery.

Verifying the HMAC Signature

If a secret was configured for your webhook, each request will include an x-hmac-signature header:

x-hmac-signature: sha256=<hex-digest>

To verify the request came from Thrive:

1. Read the raw request body as a string - do not re-parse and re-serialize the JSON, as this can alter key ordering and invalidate the signature.
2. Compute HMAC-SHA256 of the raw body string using your configured secret.
3. Compare your computed hex digest against the value after sha256= in the header.

Example (Node.js):

const crypto = require('crypto');

function verifySignature(rawBody, secret, signatureHeader) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return `sha256=${expected}` === signatureHeader;
}

OAuth 2.0 Authentication

If OAuth 2.0 is configured under auth with type: "oauth2", Thrive obtains an access token from your identity provider using the client credentials grant, then includes it on each webhook POST:

Authorization: Bearer <access_token>

auth fields

url and tokenUrl must use HTTPS. Private IPs, localhost, .internal, and .local hosts are not allowed.

Example config value (pretty-printed)

{
  "url": "https://api.example.com/learning/v1/events",
  "auth": {
    "type": "oauth2",
    "tokenUrl": "https://api.example.com/identity/v4/issue-token/token",
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret",
    "grantType": "client_credentials",
    "scope": "optional-scope"
  }
}

Behaviour

• Thrive caches tokens briefly and reuses them across deliveries for the same tenant credentials.
• If your webhook endpoint responds with 401 or 403, Thrive refreshes the token once and retries the delivery.
• You may combine OAuth with HMAC by also setting top-level secret — both Authorization and x-hmac-signature are then sent.

Your endpoint should validate the bearer token according to your identity provider (for example JWT signature and expiry, or introspection). Thrive does not define the token format; it forwards the access_token returned by your tokenUrl.

Delivery Guarantees

Events Overview

Content Events

Page Events

Post Events

Comment Events

Moderation Events

Event Lifecycle Events

Assignment Events

Enrolment Events

Notification Events

User Events