# Webhooks

> 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](https://continuumlearn.com/help/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](https://continuumlearn.com/help/recurring-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](https://continuumlearn.com/developers/enrolments) or [progress](https://continuumlearn.com/developers/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".

```json
{
  "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": "sam@example.org",
      "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:

```json
{
  "type": "course.completed",
  "data": {
    "user": { "id": 2, "email": "sam@example.org", "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
  }
}
```

```json
{
  "type": "certificate.issued",
  "data": {
    "user": { "id": 2, "email": "sam@example.org", "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](https://continuumlearn.com/developers/credentials) endpoints return the full record.

```json
{
  "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": "sam@example.org", "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.

```json
{
  "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": "sam@example.org", "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.

```json
{
  "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": "sam@example.org", "name": "Sam Patel", "external": { "id": "M-1042", "source": "acme" } }
  }
}
```

```json
{
  "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": "sam@example.org", "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](https://continuumlearn.com/developers/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](https://www.standardwebhooks.com/) specification:

1. Take the part of the secret after `whsec_` and base64-decode it. That is the HMAC key.
2. Build the signed content: `{webhook-id}.{webhook-timestamp}.{raw request body}`.
3. Compute HMAC-SHA256 of it with the key, and base64-encode the result.
4. Compare it, in constant time, with each `v1,` signature in the header. Accept the request if any matches.
5. 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
<?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'),
);
```

```js
// 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);
});
```

```python
# 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 `2xx` status 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.

```bash
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"
  }'
```

```json
{
  "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`:

```json
{
  "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

```json
{
  "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.
