Articles on: Developer Documentation

Webhooks - Get updates in real-time

Webhooks - Get updates in real-time


In this article:

  • Overview
  • How webhook delivery works
  • Step 1: Identify the events to monitor
  • Step 2: Create a webhook endpoint
  • Step 3: Handle requests from SuperPath
  • Step 4: Secure your webhook (recommended)
  • Delivery and failure behaviour
  • Managing webhooks through the API
  • Things to keep in mind
  • FAQs


Overview


SuperPath uses webhooks to notify your application when an event happens in your account. Webhooks are particularly useful for asynchronous events like when an employee completes a learning, new content is added or a user earns learning points.


A webhook enables SuperPath to push real-time notifications to your app. SuperPath sends each notification as a JSON payload over HTTPS, using a POST request to an endpoint URL you control. You can then use those notifications to execute actions in your own backend systems, without polling the API.


Before you start:


  • Webhooks are only available on paid SuperPath plans. On a free plan the Manage webhooks section shows an upgrade message instead of the webhooks table.
  • Webhooks are registered in the app, not through code — go to Settings → Integrations → Manage webhooks. See the help article How to Register a Webhook for the click-by-click steps, and How to Edit or Delete a Webhook to change one later.
  • Your production endpoint must be a publicly accessible HTTPS URL — the registration form only accepts URLs that start with https://.
  • Each webhook must subscribe to at least one event.


How webhook delivery works


When something changes in your account, SuperPath raises an internal event. For every active webhook in your account that is subscribed to that event, SuperPath sends one HTTPS POST request to that webhook's endpoint URL, with the event object as the JSON body.


You can use one endpoint to handle several different event types at once, or set up separate webhooks pointing at separate endpoints for specific events.


The high-level path to receiving webhooks is:


  1. Identify the events you want to monitor and the event payloads you need to parse.
  2. Create a webhook endpoint — an HTTP endpoint (URL) on your server.
  3. Handle requests from SuperPath by parsing each event object and returning a 2xx response status code.
  4. Deploy your webhook endpoint so it is a publicly accessible HTTPS URL.
  5. Register that HTTPS URL in Settings → Integrations → Manage webhooks.
  6. Optionally turn on signature authentication so your endpoint can verify that requests really came from SuperPath.


Tip: If you need a place to test against before going live, contact support@superpath.io and the team can look at setting up a test account for you.


Step 1: Identify the events to monitor


Decide which events your endpoint needs to react to, and which fields of the payload you will read. See Types of Events for the full list of events you can subscribe to, and The Event Object for the envelope that wraps every delivery.


Step 2: Create a webhook endpoint


Creating a webhook endpoint is no different from creating any other route on your server. It is an HTTP or HTTPS endpoint with a URL that accepts a POST request with a JSON body. While you are still developing on your local machine it can be HTTP; once it is publicly accessible and registered in SuperPath it must be HTTPS.


SuperPath does not send an API key or bearer token to your endpoint, so your endpoint must be able to accept unauthenticated POST requests. If you need to authenticate the caller, use signature authentication (Step 4).


Step 3: Handle requests from SuperPath


SuperPath sends events to your endpoint as a POST request with a JSON payload. A minimal handler looks like this:


app.post('/superpath-webhook', express.json(), (req, res) => {
  // 1. Acknowledge immediately
  res.sendStatus(200);

  // 2. Then do the work, out of band
  const { event, dateSent, dateSentOffset, data } = req.body;

  switch (event) {
    case 'user.created':
      // create the matching user in your system
      break;
    case 'learning.updated':
      // update progress / completion
      break;
    case 'points.created':
      // update a leaderboard or rewards platform
      break;
    default:
      // ignore events you do not handle yet
      break;
  }
});


Check the event object


Every delivery has the same envelope: an event name, a dateSent timestamp, a dateSentOffset, and a data object. Your endpoint must read event to work out what happened, then parse data for that event type. See The Event Object.


Return a 2xx response quickly


Return a successful status code (2xx) before running any complex logic that could time out. For example, return 200 first and then update your own records — do not make SuperPath wait while you write to your database.


Only a 2xx response counts as a successful delivery. When SuperPath receives one, it stamps that webhook's Last event date in the webhooks table.



Turn on Webhook signature auth for the webhook so SuperPath adds a SuperPath-Signature header to every request, and verify that header in your endpoint. This lets you confirm the request came from a sender who knows your secret key, rather than from a server pretending to be SuperPath.


See Webhook Signature Authentication for the verification steps, and the help article How to Secure a Webhook with Signature Authentication for where to switch it on in the app.


Delivery and failure behaviour


Delivery is at-most-once, so your endpoint should be built to tolerate a missed event rather than assume every event will arrive:


  • On a 2xx response, SuperPath records the delivery against the webhook and updates Last event in the webhooks table.
  • On any non-2xx response, or a connection error or timeout reaching your endpoint, the failure is logged on the SuperPath side and the event is not re-sent. SuperPath does not currently retry failed webhook deliveries.
  • Failed deliveries are not shown as a per-event log in the app. The signal available to you is the webhook's Last event date, which stops advancing while deliveries are failing.
  • Webhooks are only delivered while the webhook's Status is active.


Because there are no retries, treat a webhook as a notification rather than a guaranteed source of truth. If your system must stay exactly in step with SuperPath, back the webhook up with a periodic read from the SuperPath API to reconcile anything that was missed.


Managing webhooks through the API


Webhooks are normally managed in the app, but the same records are exposed on the authenticated API if you would rather script them. These endpoints use the same authentication as the rest of the API — see Learn how to authenticate with the SuperPath API.


GET    /webhooks/events/all   # list every event type you can subscribe to
GET    /webhooks              # list the webhooks in your account
GET    /webhooks/{webhookId}  # retrieve one webhook
POST   /webhooks              # create a webhook
PUT    /webhooks/{webhookId}  # update a webhook
DELETE /webhooks/{webhookId}  # delete a webhook


Full request and response schemas are in the API reference documentation.


Things to keep in mind


  • Webhooks are a paid-plan feature, and are registered under Settings → Integrations → Manage webhooks.
  • Registered endpoint URLs must start with https://.
  • SuperPath does not retry a failed delivery, so build your endpoint to be tolerant of a missed event and reconcile from the API where accuracy matters.
  • Acknowledge with a 2xx before doing your own processing — slow handlers show up as failed deliveries.
  • Handle unknown event names gracefully. New event types are added over time, so do not assume that only the events listed today will ever arrive.
  • Your endpoint may receive the same logical change more than once (for example, several rapid updates to one record), so make your handling idempotent where that matters.


FAQs


Do I need to expose an authenticated endpoint?
No. SuperPath does not send credentials with the request, so the endpoint must accept unauthenticated POST requests. Use signature authentication if you need to verify the sender.


What happens if my endpoint is down when an event fires?
The delivery fails and is logged on the SuperPath side, but it is not re-sent. Reconcile from the API for anything you cannot afford to miss.


Can one endpoint receive several event types?
Yes. Subscribe a single webhook to as many events as you like and switch on the event field, or register separate webhooks pointing at separate endpoints.


How do I test my endpoint before going live?
Contact support@superpath.io — the team can look at providing a test account for you to send events from.


Which events can I subscribe to?
See Types of Events for the current list. You can also read it programmatically from GET /webhooks/events/all.

Updated on: 25/07/2026

Was this article helpful?

Share your feedback

Cancel

Thank you!