Webhooks vs REST API
The REST API and webhooks solve opposite problems. The REST API is request-driven — you ask, the platform answers. Webhooks are event-driven — Manager Notifications POST JSON to a URL you configure in Admin. Most production integrations use both.
REST API
You pull data on demand. Best when your system needs an answer right now — looking up a user, enrolling a learner, updating a course, or backfilling history.
- Synchronous request / response
- You control the timing and the query
- Subject to rate limits — see Rate Limits
- Stateless — every call is independent
Webhooks
The platform pushes a JSON event to your URL when a Manager Notification trigger fires. Configure the URL in Users → Manager Notifications. There is no REST API to register endpoints.
- Asynchronous POST to your URL
- Same event kinds as GET /incoming/v2/events/:kind
- 15s timeout; 10 retries, 20s to 3600s (~3.5 hours)
- Success is HTTP 200–308
When to use which
| Scenario | Use | Why |
|---|---|---|
| Provision a user from your CRM | REST API | You need confirmation of success before continuing the workflow. |
| Sync course completions to an HRIS | Webhooks | Configure a courseCompletion Manager Notification instead of polling. |
| Build a custom learner dashboard | REST API | Read on-demand to render the latest state. |
| Trigger a Slack alert on enrollment | Webhooks | courseEnrollment or courseAction POSTs when the enrollment happens. |
| Nightly data warehouse export | SFTP | Use the SFTP channel on the same Manager Notification, not REST polling. |
| React to a subscription purchase or cancel | Webhooks | bundlePurchase (about a one-hour delay), subscriptionCancel, subscriptionReactivation. |
| Verify a user's certification status | REST API | Point-in-time lookup with a deterministic response. |
| Backfill missed webhook deliveries | REST API | Poll GET /incoming/v2/events/:kind from your last checkpoint. |
Use them together
The most resilient integrations combine both. The webhook tells you something changed; the REST API hydrates the full record when you need more than the event object.
1. Learner finishes a course 2. Manager Notification POSTs courseCompletion JSON → your URL 3. Your handler reads user (email) + notifiableId (course UUID) 4. Optionally call GET /v2/users/:id (full profile) 5. Optionally call GET /v2/content/course/:id (course metadata) 6. Downstream system (HRIS, CRM, warehouse) is updated
At a glance
| REST API | Webhooks | |
|---|---|---|
| Direction | Client → Platform | Platform → Client |
| Timing | On demand | On Manager Notification trigger |
| Transport | HTTPS request/response | HTTPS POST to your URL |
| Auth | Bearer API key | Configured in Admin; no webhook CRUD API |
| Failure handling | You retry | 10 attempts, 20s–3600s backoff |
| Best for | Reads, writes, lookups, backfill | Live sync, alerts |