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, retries and failures
• 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://, and SuperPath only sends to public addresses on ports 80 and 443.
• 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.

Every attempt SuperPath makes is recorded in the Webhook Logs, with the payload it sent and the response your endpoint gave. See the help article Webhook Logs: Monitor and Troubleshoot Your Webhooks.

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:

const seenDeliveries = new Set(); // use a database or cache in production

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

  // 2. Skip a delivery you have already handled (a retry of it)
  const deliveryId = req.get('SuperPath-Delivery-Id');
  if (seenDeliveries.has(deliveryId)) return;
  seenDeliveries.add(deliveryId);

  // 3. 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 or 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) within 10 seconds, before running any complex logic. For example, return 200 first and then update your own records. Do not make SuperPath wait while you write to your database: an endpoint that takes longer than 10 seconds to answer is treated as a failed attempt and is sent the event again.

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

Step 4: Secure your webhook (recommended)

Turn on Use webhook signature authentication 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, retries and failures

SuperPath retries a failed delivery, so an endpoint that is briefly down or overloaded does not lose events. It also means your endpoint can receive the same delivery more than once.

What counts as a success or a failure

• Success: your endpoint answers with any 2xx status code within 10 seconds.
• Retried: no answer within 10 seconds, a connection that could not be made or was dropped, or the status codes 408, 429, 500, 502, 503 and 504.
• Not retried: any other 4xx or 5xx status code. These end the delivery straight away.
• Redirects are not followed. A 3xx answer ends the delivery and is not retried. If your endpoint has moved, update the webhook's Endpoint URL in SuperPath.
• Only public addresses on ports 80 and 443 are called. A URL that resolves to a private or internal network address, or uses any other port, is not called and the attempt is logged as skipped.

The retry schedule

A delivery is tried up to six times. After a retryable failure, SuperPath waits before trying again:

If attempt 6 also fails, the delivery stops. Each retry only goes to the webhook that failed: other webhooks subscribed to the same event are not sent it again.

Before each retry SuperPath reloads the webhook. If it has been deleted, switched off or no longer subscribes to the event, the retry is skipped and the delivery stops. A retry is sent to the webhook's current URL, and is signed again with a fresh timestamp.

Delivery headers

Every request carries these headers, so your endpoint can tell a retry from a new event:

Seeing what happened

Every attempt, successful or not, is recorded in the Webhook Logs (Settings → Integrations → Manage Webhooks → View Webhook Logs) for 30 days, with the payload sent and your endpoint's status code and response. The webhooks table also has a Health column that shows when a webhook's recent deliveries have been failing. See the help article Webhook Logs: Monitor and Troubleshoot Your Webhooks.

Webhooks are only delivered while the webhook's Status is active. A webhook that keeps failing is not switched off automatically.

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
POST   /webhooks/{webhookId}/secret/regenerate # replace the signing secret and return it
DELETE /webhooks/{webhookId}                   # delete a webhook
GET    /webhooklogs                            # list delivery attempts (30 per page)
GET    /webhooklogs/{webhookLogId}             # one attempt, with its payload and response

To turn on signature authentication through the API, send "useSignatureAuth": true when you create the webhook. SuperPath generates a secret key and returns it once, as secretKey in the create response, next to the new webhook's id. Store it on your endpoint straight away. You can also send your own secretKey on create, and SuperPath keeps it.

After that, the secret key is never returned again. GET /webhooks and GET /webhooks/{webhookId} return secretKeySet: true instead of the key. To get a new key, call POST /webhooks/{webhookId}/secret/regenerate: it replaces the key straight away and returns the new one. A secretKey sent on an update is ignored. If you turn signature authentication on for an existing webhook with PUT, SuperPath creates a key but does not return it, so call regenerate next to get one you can use.

GET /webhooklogs accepts the filters webhookId, eventType, outcome (delivered, failed_will_retry, failed_final or skipped), search (an exact record id or delivery id), dateFrom, dateTo and page (the first page is 0).

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://, and must be public addresses on port 80 or 443.
• Acknowledge with a 2xx within 10 seconds, before doing your own processing. A slow handler is treated as a failure and is sent the event again.
• Use SuperPath-Delivery-Id to make your handling idempotent. A retry after a timeout can arrive even though your endpoint did receive and process the first attempt.
• Retries end after six attempts over about 8.5 hours. Where accuracy matters, back the webhook up with a periodic read from the SuperPath API to reconcile anything that ran out of attempts.
• 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 even without retries (for example, several rapid updates to one record), so key your updates on the record's id as well.

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?
SuperPath retries the delivery up to five more times over about 8.5 hours. Once your endpoint is back, the next retry should get through. Check the Webhook Logs for any delivery that ran out of attempts.

How do I stop processing the same event twice?
Store the SuperPath-Delivery-Id header of each delivery you have processed, and skip a request whose id you have already seen. Every attempt of one delivery carries the same id.

Why was my delivery not retried?
Your endpoint answered with a status code that is not retried, such as 400, 401, 404 or a redirect. Open the attempt in the Webhook Logs to see the status code and the response body.

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. Once you are sending events, the Webhook Logs show exactly what was sent and what your endpoint answered.

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: 26/10/2026