Skip to content
English
Contact Support
  • There are no suggestions because the search field is empty.

Webhooks

Learn how to receive event notifications from Foundry in your own system

Overview

Webhooks are outbound notifications that Foundry sends to your application when specific events occur. Webhooks are useful when your system needs to react quickly to changes in Foundry, without repeatedly polling the API.

A webhook is an HTTP POST request sent from Foundry to a payload URL you provide. Each webhook includes event details your application can use to trigger workflows, such as updating internal records when progress is completed.

How Webhooks Work

With webhooks enabled, Foundry sends an HTTP POST to your payload URL when an event occurs. Your system is responsible for:

  • Receiving the request
  • Validating the request authenticity
  • Processing the data
  • Returning an HTTP status code to Foundry

If your system successfully processes the webhook, it should return a 2XX response (typically 200). Any non‑2XX response indicates the webhook was not handled successfully.

Webhook Limitations

Webhooks complement the Foundry API, but they do not replace it. ComplyEQ aims to deliver webhooks reliably and quickly, but webhook delivery cannot be guaranteed. If you rely on webhooks for near‑real‑time workflows, use the Foundry API as a regular true‑up to confirm records are complete.

Additional limitations:

  • Webhooks may arrive out of order
  • Webhooks that are not delivered within one hour of the event will not be sent
  • Webhooks are marked inactive if Foundry cannot verify the domain’s DNS record
  • Inactive webhooks may still receive queued requests for a short period after becoming inactive

Receiving Webhooks

To receive webhooks, your organization must host an application endpoint that can:

  • Accept HTTP POST requests
  • Parse JSON request bodies
  • Return an HTTP status code based on processing outcome

Your webhook endpoint should return:

  • 2XX if the event was handled successfully
  • A non‑2XX status code if the event could not be handled

This response behavior is important because webhook delivery and retry behavior may depend on whether Foundry considers the delivery successful.

Manage Webhooks in Foundry

To configure webhooks, log in to Foundry with administrative access and go to:

Settings > Webhooks

Setup happens in two parts:

  1. Add and verify a webhook domain
  2. Add a webhook path and select the events you want to receive

Add a Webhook Domain

When adding a domain, you associate it with a registered API and define the domain that will receive webhook requests.

Example
If your payload URL is:

https://integrations.mysite.com/api/webhooks

Then enter the domain as:

integrations.mysite.com

After saving the domain, Foundry displays two tokens:

  • Verification Token
  • Secret Token

Save both immediately. These values are visible only briefly. If needed, you can regenerate either value later.

Verification Token
Used to verify domain ownership in DNS.

Secret Token
Used to digitally sign webhook requests so your system can verify the webhook came from Foundry.

Add a Webhook Path and Select Events

After the domain is created, add a webhook to define:

  • The path on your domain
  • The event types that should trigger deliveries

Example
If your payload URL is:

https://integrations.mysite.com/api/webhooks

Then:

  • Domain: integrations.mysite.com
  • Path: api/webhooks (no leading slash)

After your domain is verified, you can toggle the webhook to Active.

Manage Domains and Webhooks

Once configured, you can manage the following:

Domain actions

  • View verification status
  • Verify the domain on demand
  • Regenerate the Verification Token or Secret Token
  • Delete the domain

Webhook actions

  • Send a test webhook after verification
  • Add or delete webhooks
  • Edit an existing webhook (toggle Active, copy Webhook ID, change event selections)

Important behavior:

  • To change the domain, delete the domain and add a new one
  • To change the path, delete the webhook and create a new one with the updated path

Verify Your Domain

Foundry sends webhooks only after domain verification. This helps ensure learner data is delivered only to systems you control.

To verify your domain, create a DNS TXT record:

  • Record type: TXT
  • Host: your domain
  • Value: _everfi_webhooks=secret-token (use the token Foundry provides)
  • TTL: use your default value

Foundry checks this DNS record on a scheduled basis (including nightly). If you need to validate immediately, use the Verify option in Foundry.

Your webhook endpoint must be secured with HTTPS.

Webhook Security Headers

Webhook requests include header values you should use to validate authenticity. Foundry signs webhooks using a request‑signing method (for example, HMAC signatures). Your integration should generate its own signature using the secret token and compare it to the signature in the webhook headers.

Common headers include:

  • HTTP_AUTHORIZATION
    Contains the signature components (digest, public key, signature)

  • REQUEST_METHOD
    Always POST and used when generating the signature

  • REQUEST_URI
    Used when generating the signature

  • CONTENT_TYPE
    Typically application/json and used when generating the signature

  • HTTP_DATE
    Use this to confirm the request timestamp is within a reasonable window

  • HTTP_CONTENT_MD5
    A hash of the request body used when generating the signature

Webhook Data

All webhook payloads include common fields in the request body:

  • event_id (uuid)
    A unique event identifier. If a webhook is delivered more than once, it may reuse the same event_id. Your system should avoid processing the same event_id multiple times.

  • event_type (string)
    The event that triggered delivery

  • event_time (timestamp)
    When the event occurred

  • data (array)
    Event‑specific information relevant to the event_type

Supported Event Types

Foundry currently supports webhook events such as:

  • user_assignment.progress.completed
  • program_user.progress.completed

Each event type includes different data objects in the data array.

Event Data: user_assignment.progress.completed

This event includes data that identifies:

  • The user
  • The content assigned
  • The progress record and completion details

User fields may include

  • id
  • first_name
  • last_name
  • email
  • employee_id (if present)
  • sso_id (if present)
  • active
  • location
  • groupings (categories and labels)

Progress fields may include

  • id
  • content_id
  • due_on
  • last_progress_at
  • name
  • percent_completed
  • content_status (not_started, in_progress, completed, skipped)
  • started_at
  • completed_at

Event Data: program_user.progress.completed

This event includes information about:

  • The user
  • The program or playlist the user completed

For detailed attribute definitions, use the Program User API documentation, which aligns with the webhook payload fields for this event.