Webhooks

About This Feature

Webhooks allow for real-time, event-level data to be pushed from Disco into external systems. This enables timely automation and richer data analysis outside the Disco platform. Admins can use webhooks to track learner engagement outside of Disco, update external dashboards, sync progress to CRMs, without manually polling the API or relying on pre-aggregated data.

 

How It Works

Webhook endpoints are configured directly within the Disco platform. Admins can configure one or more target urls to receive events, and subscribe each url to a set of events. Once an event occurs in Disco (e.g., a learner completes a lesson), the relevant payload is pushed to the configured endpoint(s) in real-time. Webhooks are signed for security, and delivery logs are for 30 days available to monitor success or failure. Retry functionality is available manually through the platform for failed deliveries.

 

How To Configure Endpoints

  1. Go to Admin > Settings > Webhooks.
  2. Click “+ Endpoint”.
  3. Provide an endpoint URL.
  4. Optionally configure custom headers.
  5. Select events to send to this endpoint URL. Multiple events can be sent to the same URL. Full details on webhook events available via Disco can be found here.
  6. Click “Save”. This will create the webhook in an enabled state, and events will be sent to the endpoint starting immediately.

To disable an endpoint:

  1. Go to Admin > Settings > Webhooks.
  2. Locate the endpoint to be disabled.
  3. Open the Action menu, and select “Disable Endpoint”.

 

How To View Event History & Retry Events

  1. Go to Admin > Settings > Webhooks.
  2. Locate the desired endpoint.
  3. Open the Action menu, and select “View Event Logs”.
  4. Use filters and/or search to locate specific events.
  5. Select an event to view its details, including response, headers and payload.
  6. To retry an event, locate the failed event, then click the vertical … for that event. Select “Resend” from the dropdown to resend the event.

Validating Signed Requests

Every webhook request is signed using the RFC-9421 standard. Disco uses the endpoint Signing Secret to create the Signature, constructed from the components specified in the Signature-Input header. The Content-Digest header can be used to verify the integrity of the message content.

We recommend using the http-message-signatures package to verify the request.

See a minimal example in Typescript, below:

async function validateSignedRequest(
   request: {
     method: string
     url: string
     headers: Record<string, string | string[]>
     body: any
   },
   // Signing Secret from the endpoint config in platform
   signingSecret: string
 ): Promise<boolean> {
   // Verify the message signature
   const verified = Boolean(
     await httpbis.verifyMessage(
       {
         keyLookup: async () => {
           return {
             id: "shared-secret"
             alg: ["hmac-sha256"],
             verify: createVerifier(signingSecret, "hmac-sha256"),
           }
         },
       },
       request
     )
   )
    // Verify the content digest matches the body
   const contentDigest = request.headers["Content-Digest"] as string
    const data = JSON.stringify(request.body)
    const expectedDigest = `sha-512=:${crypto
     .createHash("sha512")
     .update(data)
     .digest("base64")}:`
    const digestMatches = contentDigest === expectedDigest
    return verified && digestMatches
 }

Important Considerations

  • Webhook functionality is only available on an Enterprise plan.
  • Event delivery order is not guaranteed.
  • Failed events must be retried one event at a time. No bulk retries.
  • SSL is required for all endpoints. Custom headers are optional.
  • Timeout duration (10 seconds) is fixed and cannot be configured.

 

FAQs

Q: What happens if my endpoint is temporarily down?
 A: The webhook delivery will fail, and no automatic retry will occur. The event can be manually retried from the Event Log in the platform.

Q: Can webhook events be sent to multiple endpoints?
 A: Yes, the same event can be sent to multiple endpoints.

Q: What happens to an endpoint while it is disabled?
 A: No new events will be sent to the endpoint while the endpoint is disabled. The endpoint config can be edited while disabled. Logs for events within a 30 day period are preserved. The endpoint can be re-enabled at any time.

Q: Are webhook requests secure?

A: Yes. All webhook requests are SSL-encrypted and signed. Custom headers can also be added for additional security.

Q: What happens when I retry an event?

A: The identical payload with the current webhook config (url, custom headers) will be resent. A new event log with the same event id will indicate delivery success or failure.

Q: How long are historical events available to view within Disco?

A: Event logs are available for the previous 30 day period.