> ## Documentation Index
> Fetch the complete documentation index at: https://docs.edplay.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Edplay Webhooks Overview

> Webhooks push learner progress from Edplay to your systems the moment it happens, so you never have to poll the API for changes.

Webhooks let Edplay push learner progress to your systems the moment it happens, instead of you polling the API for changes. When a learner finishes a course, Edplay sends an HTTP `POST` to a URL you control, carrying who did what and when.

Common uses:

* Mark training complete in your HRIS.
* Issue a certificate as soon as a course is finished.
* Unlock the next step in an onboarding flow.
* Stream completion data into your data warehouse.

<Note>
  Each workspace has **one** webhook endpoint. You configure it in **Workspace Settings** > **Integrations** > **Webhooks**.
</Note>

## How a delivery works

<Steps>
  <Step title="An event happens">
    A learner completes a course, or their progress through a course changes.
  </Step>

  <Step title="Edplay builds and signs the payload">
    Edplay serializes the event as JSON and signs it with your workspace signing secret.
  </Step>

  <Step title="Edplay sends the request">
    A `POST` goes to your endpoint URL, carrying a `Signature` header and a `Timestamp` header.
  </Step>

  <Step title="Your endpoint responds">
    Verify the signature, queue the payload, and return a `2xx` status within 3 seconds.
  </Step>

  <Step title="The attempt is logged">
    The result appears in the delivery log as **Pending**, **Delivered**, or **Failed**.
  </Step>
</Steps>

## Before you start

| Requirement                 | Detail                                                                                                                                  |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Workspace admin role        | Only workspace admins can view or change webhook settings.                                                                              |
| An HTTPS endpoint           | Plain `http://` URLs are rejected. The TLS certificate must be valid and publicly trusted, so self-signed certificates fail.            |
| A publicly reachable URL    | Edplay calls from its own servers, so `localhost` and private IP ranges do not work. For local development, use a tunnel such as ngrok. |
| A response within 3 seconds | Anything slower counts as a failed delivery and triggers a retry.                                                                       |

<Warning>
  The 3-second limit is the most common cause of failed deliveries. Never do real work inside the request. See [Deliveries and retries](/webhooks/deliveries).
</Warning>

## Where to go next

<CardGroup cols={2}>
  <Card title="Set up your endpoint" icon="plug" href="/webhooks/setup">
    Configure the URL, choose your events, and confirm the connection with a test delivery.
  </Card>

  <Card title="Events and payloads" icon="code" href="/webhooks/events">
    Every event Edplay sends, and the exact shape of each payload.
  </Card>

  <Card title="Verify signatures" icon="shield-check" href="/webhooks/verify-signature">
    Prove a request came from Edplay, with Node.js, PHP, and Python examples.
  </Card>

  <Card title="Deliveries and retries" icon="arrows-rotate" href="/webhooks/deliveries">
    How to respond, when Edplay retries, and how to read the delivery log.
  </Card>
</CardGroup>