In short
Webhooks POST a JSON event to your HTTPS endpoint when something happens, such as a user joining, an enrolment or a completion. Each request is signed to the Standard Webhooks specification, so you can verify it with off-the-shelf libraries. Failed deliveries are retried for about 27 hours and can be redelivered.
Webhooks let your system react to what happens in Continuum Learn without polling the API. When an event happens, Continuum sends an HTTPS POST to each enabled endpoint that subscribes to it.
Set endpoints up in Settings > Website & API > Webhooks (see the help guide How to send events to another system with webhooks), or through the API with the webhooks:manage scope.
Events
| Type | Sent when | data |
|---|---|---|
user.created |
Someone joins the team for the first time: registration, an accepted invitation, single sign-on, the API or a membership-system sync. Re-adding an existing member doesn't send it. | user |
user.removed |
Someone is removed from the team, in Manage, through the API or by a membership-system sync. | user, as last seen |
enrolment.created |
A user gets a direct enrolment on a course: from the API, an administrator, self-enrolment, an approved request, a paid order or a required training requirement being applied to them. | enrolment, user, course |
enrolment.removed |
A user's direct enrolment is removed, including when a required-training enrolment is released (the learner left the requirement's audience, or the requirement was deleted, before they started the current cycle). | enrolment, user, course |
course.completed |
A learner completes a course. For a course with a recurring training requirement this fires once per cycle: each renewal that the learner completes sends a new event. | user, course, completed_at, percentage |
certificate.issued |
A course or programme certificate is issued, including a new certificate when one is renewed. For recurring training a new certificate is issued once per cycle, and so is this event. | user, certificate |
order.completed |
A checkout order is paid for and completed. | order, user |
order.refunded |
A refund of an order succeeds, whether it was made in Manage or in the Stripe dashboard. A refund that is still pending, or fails, sends nothing. | order, refund, user |
invoice.issued |
A tax invoice (or receipt, for a team that isn't VAT registered) is issued for a completed order. Only teams that issue invoices send it. | invoice, user |
credit_note.issued |
A credit note is issued for a refund of an invoiced order. | credit_note, user |
ping |
Someone sends a test event from Manage or the API. Never sent otherwise. | message |
Each real occurrence is sent once, after the change has been saved: a change that is rolled back sends nothing. GET /v2/webhook-event-types returns this catalogue with descriptions.
Activating a recurring training requirement on a large audience sends one enrolment.created per newly enrolled learner, spread over the background run rather than all at once. A learner who is already enrolled is not enrolled again, so sends nothing.
Enrolments through groups don't send enrolment events. When a group is assigned to a course, or someone joins a group that is, nothing is sent for each member. If you rely on group assignment, read enrolments or progress through the API instead.
If you use the older credential webhook (on the Settings > Webhooks page), it keeps working unchanged. certificate.issued is its general-purpose successor.
Payload
Every event has the same envelope:
| Field | Description |
|---|---|
id |
The event id, evt_ followed by a ULID. Also sent as the webhook-id header. |
type |
The event type. |
created_at |
When the event happened, in UTC, like 2026-11-09T14:03:11Z. |
team_id |
Your team's id. |
data |
The event's data. It reuses the API's own shapes, so code that reads the API can read events too. |
The user in every event is the compact user from the API: {id, email, name, external: {id, source}}, where external.id and external.source are strings, or null when the user has no external id. Dates inside data use the API's format, like 2026-11-09T14:03:11+00:00.
Key order isn't guaranteed. The order of keys in the delivered JSON can differ from the examples here (events are stored as JSON, which reorders keys), so parse the JSON rather than depending on its layout. The signature covers the exact bytes you receive.
data is built when the event is first sent, normally within seconds, so it shows the record as it is at that moment. Retries and redeliveries send exactly the same body as the first attempt. If the record can no longer be read by then (for example, the user was deleted in the meantime), the delivery fails with the error "The event payload could not be built".
{
"id": "evt_01M70BNQK9KZBZ5NJ4NTP6X3J1",
"type": "enrolment.created",
"created_at": "2026-11-09T14:33:54Z",
"team_id": 58,
"data": {
"enrolment": {
"user_id": 2,
"course_id": 412,
"status": "enrolled",
"enrolled_at": "2026-11-09T14:33:54+00:00",
"unenrolled_at": null,
"sources": [{ "type": "direct", "enrolled_at": "2026-11-09T14:33:54+00:00" }],
"offered_via_group_ids": [],
"request": null
},
"user": {
"id": 2,
"email": "[email protected]",
"name": "Sam Patel",
"external": { "id": "M-1042", "source": "acme" }
},
"course": { "id": 412, "title": "Food Safety Level 2" }
}
}
enrolment.removed has the same shape, with the enrolment as it is after the removal (usually status: unenrolled; still enrolled if the user is also enrolled through a group).
The data of the other events:
{
"type": "course.completed",
"data": {
"user": { "id": 2, "email": "[email protected]", "name": "Sam Patel", "external": { "id": "M-1042", "source": "acme" } },
"course": { "id": 412, "title": "Food Safety Level 2" },
"completed_at": "2026-11-09T14:33:54+00:00",
"percentage": 100
}
}
{
"type": "certificate.issued",
"data": {
"user": { "id": 2, "email": "[email protected]", "name": "Sam Patel", "external": { "id": "M-1042", "source": "acme" } },
"certificate": {
"number": "CL-58-01M70BNQMBD7GRTW9QZ33R63W4",
"kind": "course",
"title": "Food Safety Level 2",
"awarded_at": "2026-11-09T14:33:54+00:00",
"expires_at": "2029-11-09T14:33:54+00:00",
"verify_url": "https://acme.continuumlearn.com/verify/..."
}
}
}
percentage in course.completed is a JSON number rounded to 2 decimal places: a whole value arrives as 100, a fractional one as 87.46.
kind is course or programme. expires_at is null for a certificate that doesn't expire, and verify_url is null unless public verification is turned on in the certificate template. The credentials endpoints return the full record.
{
"type": "order.completed",
"data": {
"order": {
"id": 9021,
"total": "45.00",
"subtotal": "50.00",
"discount": "5.00",
"tax": "0.00",
"coupon": { "code": "MEMBER10" },
"currency": "GBP",
"invoice_number": "INV-00042",
"items": [{ "type": "course", "id": 412, "title": "Food Safety Level 2", "quantity": 1, "unit_price": "50.00", "tax_rate": "0.00" }],
"completed_at": "2026-11-09T14:33:54+00:00"
},
"user": { "id": 2, "email": "[email protected]", "name": "Sam Patel", "external": { "id": "M-1042", "source": "acme" } }
}
}
total, subtotal, discount and tax are decimal strings in the order's currency (not minor units), and each item's unit_price is too. currency is an ISO 4217 code: the examples show GBP, but it may be another code for a team that sells in a different currency. subtotal and discount are both before VAT (also for teams that enter prices including VAT), so subtotal - discount + tax = total. discount is the amount taken off by a discount code, before VAT, and coupon is { "code": "..." } when a code was used, otherwise null. Each item's quantity is a whole number. Each item's type is course, bundle, event_ticket, programme or other. user is null for a guest checkout. invoice_number is the number of the invoice issued for the order, or null when none was (the team doesn't issue invoices, or it isn't issued yet: invoice.issued follows). Each item's tax_rate is the VAT rate as a percentage decimal string, or null on orders placed before tax rates were recorded.
{
"type": "order.refunded",
"data": {
"order": { "id": 9021, "total": "45.00", "subtotal": "50.00", "discount": "5.00", "tax": "0.00", "coupon": null, "currency": "GBP", "items": [], "completed_at": "2026-11-09T14:33:54+00:00" },
"refund": { "id": 31, "amount": "15.00", "full": false, "created_at": "2026-11-12T09:02:11+00:00" },
"user": { "id": 2, "email": "[email protected]", "name": "Sam Patel", "external": { "id": "M-1042", "source": "acme" } }
}
}
order has the same shape as in order.completed (items is abbreviated above). refund.amount is a decimal string in the order's currency, the gross amount returned to the card, and refund.full is true when this refund brings the order's total refunded up to its total. One event is sent per refund that succeeds.
{
"type": "invoice.issued",
"data": {
"invoice": {
"number": "INV-00042",
"issued_at": "2026-11-09T14:33:55+00:00",
"currency": "GBP",
"subtotal": "50.00",
"discount": "5.00",
"tax": "0.00",
"total": "45.00",
"reverse_charge": false,
"order_id": 9021
},
"user": { "id": 2, "email": "[email protected]", "name": "Sam Patel", "external": { "id": "M-1042", "source": "acme" } }
}
}
{
"type": "credit_note.issued",
"data": {
"credit_note": {
"number": "CN-00003",
"credits_invoice_number": "INV-00042",
"issued_at": "2026-11-12T09:02:12+00:00",
"currency": "GBP",
"tax": "0.00",
"total": "15.00",
"order_id": 9021
},
"user": { "id": 2, "email": "[email protected]", "name": "Sam Patel", "external": { "id": "M-1042", "source": "acme" } }
}
}
Money is decimal strings in the document's currency (an ISO code, GBP in the examples). subtotal and discount are before VAT, so subtotal - discount + tax = total. A credit note has no subtotal or discount: total is the amount credited including tax. user is null for a guest checkout. The orders endpoints return the full documents.
user.created and user.removed carry {"user": {...}}, and ping carries {"message": "Test event from Continuum Learn"}.
Very large events
If an event would be bigger than 64 KB, data is cut down before it is sent: it keeps its top-level plain values (text cut to 500 characters), keeps only the id of each nested object that has one, drops other nested values, and gains "truncated": true. When you see truncated, fetch the full record from the API.
Request headers
POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: ContinuumLearn-Webhooks/1.0
webhook-id: evt_01M70BNQK9KZBZ5NJ4NTP6X3J1
webhook-timestamp: 1762699234
webhook-signature: v1,8PtZRDe70GifHhbFBIptiKjaDZfHpiuux49G8nc0kMc=
| Header | Meaning |
|---|---|
webhook-id |
The event id. The same on every retry and redelivery: use it to ignore duplicates. |
webhook-timestamp |
When this attempt was sent, in Unix seconds. |
webhook-signature |
v1, followed by the base64 HMAC-SHA256 signature. For 24 hours after a secret rotation it holds two signatures separated by a space, the new secret's first. |
Verify the signature
Each endpoint has a signing secret, shown once when you create it, in the form whsec_ followed by base64. Keep the whsec_ prefix when you store it: the libraries below expect the whole value. Signatures follow the Standard Webhooks specification:
- Take the part of the secret after
whsec_and base64-decode it. That is the HMAC key. - Build the signed content:
{webhook-id}.{webhook-timestamp}.{raw request body}. - Compute HMAC-SHA256 of it with the key, and base64-encode the result.
- Compare it, in constant time, with each
v1,signature in the header. Accept the request if any matches. - Reject it if the timestamp is more than 5 minutes from your clock, to stop replays.
Always verify against the raw body exactly as received. Parsing the JSON and serialising it again changes the bytes and the signature won't match.
<?php
// Plain PHP, no library. (Or: composer require standard-webhooks/standard-webhooks)
function verifyContinuumWebhook(string $body, array $headers, string $secret): array
{
$headers = array_change_key_case($headers, CASE_LOWER);
$id = $headers['webhook-id'] ?? '';
$timestamp = $headers['webhook-timestamp'] ?? '';
$signatures = explode(' ', $headers['webhook-signature'] ?? '');
if (! ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) {
throw new RuntimeException('Timestamp outside the tolerance');
}
$key = base64_decode(substr($secret, strlen('whsec_')), true);
$expected = 'v1,'.base64_encode(hash_hmac('sha256', "{$id}.{$timestamp}.{$body}", $key, true));
foreach ($signatures as $signature) {
if (hash_equals($expected, $signature)) {
return json_decode($body, true);
}
}
throw new RuntimeException('Invalid signature');
}
// In your endpoint:
$event = verifyContinuumWebhook(
file_get_contents('php://input'),
[
'webhook-id' => $_SERVER['HTTP_WEBHOOK_ID'] ?? '',
'webhook-timestamp' => $_SERVER['HTTP_WEBHOOK_TIMESTAMP'] ?? '',
'webhook-signature' => $_SERVER['HTTP_WEBHOOK_SIGNATURE'] ?? '',
],
getenv('CONTINUUM_WEBHOOK_SECRET'),
);
// npm install standardwebhooks express
import express from 'express';
import { Webhook } from 'standardwebhooks';
const wh = new Webhook(process.env.CONTINUUM_WEBHOOK_SECRET); // the whsec_... value
const app = express();
// Keep the raw body: verification needs the exact bytes.
app.post('/continuum/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
let event;
try {
event = wh.verify(req.body.toString('utf8'), {
'webhook-id': req.header('webhook-id'),
'webhook-timestamp': req.header('webhook-timestamp'),
'webhook-signature': req.header('webhook-signature'),
});
} catch (err) {
return res.status(400).send('Invalid signature');
}
// Acknowledge quickly, then do the work (ideally on a queue).
res.sendStatus(204);
handle(event);
});
# pip install standardwebhooks flask
import os
from flask import Flask, request
from standardwebhooks.webhooks import Webhook, WebhookVerificationError
wh = Webhook(os.environ["CONTINUUM_WEBHOOK_SECRET"]) # the whsec_... value
app = Flask(__name__)
@app.post("/continuum/webhooks")
def continuum_webhook():
try:
event = wh.verify(request.get_data(), {
"webhook-id": request.headers.get("webhook-id", ""),
"webhook-timestamp": request.headers.get("webhook-timestamp", ""),
"webhook-signature": request.headers.get("webhook-signature", ""),
})
except WebhookVerificationError:
return "Invalid signature", 400
handle(event) # ideally hand off to a queue
return "", 204
Responding, retries and duplicates
- Return any
2xxstatus within 10 seconds (5 seconds to connect) to acknowledge an event. Anything else counts as a failure, including redirects (3xx), which are not followed. - Do the work afterwards. Acknowledge first and process the event on a queue, so a slow job doesn't cause a timeout and a retry.
- Expect duplicates. A retry or a redelivery has the same
webhook-id. Store the ids you've handled and skip repeats. - Don't rely on order. Events can arrive out of order, especially after retries. Use
created_at, or fetch the current state from the API when order matters.
A failed delivery is retried on this schedule (the Standard Webhooks schedule):
| Attempt | Delay after the previous one |
|---|---|
| 1 | Immediately |
| 2 | 5 seconds |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 5 hours |
| 7 | 10 hours |
| 8 | 10 hours |
That is 8 attempts over about 27 hours. A delivery's status is pending before its first attempt, retrying between attempts, and succeeded or failed at the end. Some failures end a delivery straight away, without retries:
- the endpoint's address now resolves to a private or internal network address (checked before every attempt, because DNS can change);
- the endpoint has been disabled (except for a test
ping); - the endpoint has been deleted.
If an attempt crashes on our side, it counts as a failed attempt and is retried on the same schedule. If a delivery is ever left without an attempt queued (for example after a server restart), a recovery check that runs every 5 minutes queues it again once it is 10 minutes overdue.
Deliveries are kept for 30 days. You can redeliver any delivery that has finished (succeeded or failed): a redelivery is a new delivery with the same event id and payload. Asking to redeliver one that is still pending or retrying returns 409 with error.code delivery_in_progress.
Automatic disabling
Every delivery that the endpoint fails (one that ends as failed after being attempted) adds one to its consecutive_failures, and any successful delivery resets it to zero. Failed attempts that a later retry recovers don't count, and nor do deliveries that failed only because the endpoint was disabled or deleted. When an endpoint reaches 50 failed deliveries in a row and has had no success for 5 days (or, if it has never succeeded, was created more than 5 days ago), it is disabled with disabled_reason: failing, and the team's administrators and owners are emailed.
While an endpoint is disabled, no new events are queued for it, and deliveries already waiting for a retry fail when their next attempt comes round. Events that happen in the meantime are not saved up. To start again, fix the receiving system, re-enable the endpoint in Manage or with PATCH {"enabled": true} (which also resets consecutive_failures), send a test, then redeliver any events you need from the delivery log.
A test ping is delivered even to a disabled endpoint, so you can check a fix before re-enabling it.
Rotating the secret
Rotate an endpoint's secret in Manage, or with POST /v2/webhook-endpoints/{id}/rotate-secret. The new secret is shown once. For 24 hours afterwards every delivery is signed with both the new and the old secret (previous_secret_expires_at on the endpoint says until when), so you can deploy the new one without missing events. After that only the new secret signs.
Managing endpoints through the API
These endpoints need the webhooks:manage scope. Paths are relative to /api/v2.
| Method | Path | What it does |
|---|---|---|
| GET | /webhook-event-types |
The event catalogue |
| GET | /webhook-endpoints |
List endpoints (cursor-paginated) |
| POST | /webhook-endpoints |
Create an endpoint. 201, with the secret shown only this once. |
| GET | /webhook-endpoints/{id} |
One endpoint |
| PATCH | /webhook-endpoints/{id} |
Change url, events, description or enabled |
| DELETE | /webhook-endpoints/{id} |
Delete it (204). Retries still waiting for it are abandoned. |
| POST | /webhook-endpoints/{id}/rotate-secret |
A new secret, shown once |
| POST | /webhook-endpoints/{id}/test |
Queue a ping. 202 with the new delivery. |
| GET | /webhook-endpoints/{id}/deliveries |
The delivery log, newest first, without payloads. Filter with status (pending, retrying, succeeded, failed) and event_type. |
| GET | /webhook-endpoints/{id}/deliveries/{delivery_id} |
One delivery, with its payload |
| POST | /webhook-endpoints/{id}/deliveries/{delivery_id}/redeliver |
Send a finished delivery again. 202 with the new delivery; 409 delivery_in_progress if it is still pending or retrying. |
Create an endpoint
events is a list of event types, or ["*"] for every event, including any added later. ping can't be subscribed to. description is optional, up to 255 characters.
curl https://your-team.continuumlearn.com/api/v2/webhook-endpoints \
-H "Authorization: Bearer $CONTINUUM_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: webhook-ams-1" \
-d '{
"url": "https://ams.example.org/continuum/webhooks",
"events": ["user.created", "enrolment.created", "course.completed", "certificate.issued"],
"description": "Membership system"
}'
{
"data": {
"id": 3,
"url": "https://ams.example.org/continuum/webhooks",
"description": "Membership system",
"events": ["user.created", "enrolment.created", "course.completed", "certificate.issued"],
"enabled": true,
"disabled_reason": null,
"consecutive_failures": 0,
"last_success_at": null,
"last_failure_at": null,
"previous_secret_expires_at": null,
"created_at": "2026-11-09T14:33:54+00:00",
"updated_at": "2026-11-09T14:33:54+00:00",
"secret": "whsec_ZXhhbXBsZS1zZWNyZXQtZG8tbm90LXVzZS0wMDAwMDAw"
}
}
secret appears only in the responses to create and rotate-secret. disabled_reason is null, manual or failing.
The URL must use https, be at most 2,048 characters and resolve to a public address: private and internal network addresses are refused when you save the endpoint and again before every delivery. A team can have up to 10 endpoints. A bad URL, an 11th endpoint or an unknown event type returns 422 validation_error with the reason under details.url or details.events:
{
"error": {
"type": "validation_error",
"message": "The given data was invalid.",
"details": { "url": ["Destination host 127.0.0.1 resolves to a non-public address."] }
},
"request_id": "01M70BNQPKE6MK6XVEGVC3Y0VT"
}
Deliveries
{
"data": {
"id": 118,
"endpoint_id": 3,
"event_id": "evt_01M70BNQK9KZBZ5NJ4NTP6X3J1",
"event_type": "enrolment.created",
"status": "retrying",
"attempts": 2,
"next_attempt_at": "2026-11-09T14:39:00+00:00",
"last_status_code": 503,
"last_error": "Receiver responded with HTTP 503.",
"last_response_snippet": "Service Unavailable",
"delivered_at": null,
"created_at": "2026-11-09T14:33:54+00:00"
}
}
last_error and last_response_snippet hold up to 500 characters. Fetching a single delivery adds payload, the exact event that was sent. Before its first attempt, an event's payload is a short internal placeholder ({"pending": true, "refs": {...}} plus the event's id, type and time); it becomes the full event once the first attempt has been made. Test and redeliver return the new delivery straight away, usually still pending: read the delivery again, or the list, for the outcome.
Frequently asked questions
Can I receive webhooks on localhost while developing?
Not directly, because the URL must be public HTTPS. Use a tunnelling tool that gives you a public HTTPS address forwarding to your machine, and point a test endpoint at it.
Is the payload the same as the API?
Yes. data uses the same shapes as the API's resources, so you can share the code that reads them.
Which IP addresses do webhooks come from?
We don't publish a fixed list of addresses, so don't allow-list by IP. Verify the signature instead: it proves the request came from Continuum and wasn't changed.