Introduction to Webhooks

Webhooks let Beedeez call a URL on your side when an event occurs, instead of your application polling the API for changes.

What are Webhooks?

A webhook is an HTTP POST request that Beedeez sends to an endpoint URL you declare. Today a single event reaches your endpoint: certificate_completed, sent when a learner is awarded a certificate and, under the same name, when an award reaches its expiry date (see Event Types).

How Webhooks Work

1. Configuration: an administrator declares webhook endpoints in the Beedeez back office, with:

   • a name and the URL to call
   • the event types the endpoint subscribes to
   • an authentication method (bearer token, basic auth, API key or a single custom header)

2. Event occurs: a learner meets a certificate rule, a certificate award passes its expiry date, or Beedeez runs a catch-up pass that creates missing awards.

3. Notification sent: for each award and each enabled endpoint subscribed to the event, Beedeez sends one POST request whose JSON body is the certificate award itself.

4. Your response: your endpoint returns an HTTP 2xx status within 5 seconds to acknowledge the request.

5. No retry: a non-2xx response, a timeout or a network error is logged on the Beedeez side and the notification is dropped. Beedeez does not send it again.

Benefits of Using Webhooks

• Near real-time updates: a certificate award is pushed as soon as it is recorded
• Fewer API calls: no need to poll the certificates list continuously
• Event-driven integrations: trigger actions in your systems when a learner is certified

Because a failed delivery is never replayed, pair webhooks with a periodic reconciliation through the public API (GET /v1/certificates with updatedSince) if you cannot afford to miss an event.

Use Cases

• Certificate management: notify your HR system when an employee earns a certification
• Compliance follow-up: react when a certificate award expires (delivered as certificate_completed with expiryReminderSent: true)
• Learning analytics: record certificate awards in your data warehouse

No event exists for learners, capsules, tracks or sessions. Use the public API for those.

Getting Started

1. Read the Configuration Guide to set up an endpoint
2. Review the Event Types Reference to see what is actually emitted
3. Choose an Authentication Option to protect your endpoint
4. Check the Payload Examples to see the data you will receive

Important Considerations

• Authentication is your only proof of origin: Beedeez does not sign requests. Always configure an authentication method and treat the URL as a secret.
• Respond within 5 seconds: acknowledge first, process afterwards.
• Idempotency: the same notification can reach you more than once; deduplicate on the award _id combined with expiryReminderSent (the expiry notification reuses the _id of the award).
• No envelope: the body carries no event name, delivery identifier or send timestamp.
• No retry: a failed delivery is lost; reconcile through the API.

Support

If you need help with webhooks, please contact our support team.