Event Types Reference

This page lists the webhook events Beedeez actually sends and what triggers each of them.

Emitted events

Beedeez sends a single event today: certificate_completed.

The back-office form also offers certificate_expired. No process sends it: an endpoint subscribed only to certificate_expired never receives a call. No event exists for learners, capsules, tracks or sessions.

certificate_completed

Sent when a certificate award is recorded for a learner. Three paths trigger it:

1. A learner meets a certificate rule. The call is sent in real time, when the learner's activity satisfies the rule. Only certificate rules send it: gamification badges never trigger a call.
2. A certificate reaches its expiry date. An hourly job picks up expired awards, sends the reminder email, then sends certificate_completed again for the same award, with expiryReminderSent: true. This path only covers capsule certificates (ruleType: "certifCapsule") with a validity period and the expiry reminder enabled. It runs once per award.
3. Beedeez runs a catch-up pass on a certificate to award what eligible learners are missing. One call per award created.

Telling an award from an expiry. Both arrive as certificate_completed with the same body. Read expiryReminderSent: false on the award, true on the expiry call. Comparing expires with the current time confirms it.

Subscribing

Each endpoint lists the event types it receives. Only endpoints that are enabled and subscribed to the event type are called.

{
    "name": "Certificate notifications",
    "url": "https://api.example.com/webhooks/beedeez",
    "eventTypes": ["certificate_completed"]
}

Payload

The body is the certificate award itself (a BadgeUser document), read from the database when the call is sent and posted as JSON. There is no envelope: no event name, no delivery identifier, no emission timestamp.

{
    "_id": "6712a9f4c3b5e10d2f8a4471",
    "_ownerId": "5f2c1ab8d9e4470012a3c001",
    "_userId": "66e1b0447a2c9d0011f4e882",
    "_badgeId": "64c73f10ae5b220019d0a1c7",
    "name": "Electrical safety B1V",
    "ruleType": "certifCapsule",
    "creationDate": "2026-03-11T09:42:18.204Z",
    "expires": "2027-03-11T00:00:00.000Z",
    "expiryReminderSent": false,
    "disabled": false,
    "acknowledged": false,
    "successRate": 92,
    "_lessonActiveIds": ["66f0d2213b8c4a0014ee7710"],
    "createdAt": "2026-03-11T09:42:18.209Z",
    "updatedAt": "2026-03-11T09:42:18.209Z"
}

Field	Content
_id	The award. Stable, use it as your idempotency key
_userId, _badgeId, _ownerId	The learner, the certificate definition, the account
name, ruleType	The certificate name at award time, and certifCapsule or certifSkill
creationDate	When the certificate was obtained
expires	Expiry date, null when the certificate does not expire
expiryReminderSent	true on the call sent by the expiry job
disabled	true when the award was created already expired, or withdrawn from a learner no longer eligible
acknowledged	The learner has seen the certificate in the app

description, name_i18n, description_i18n, score, successRate, correctAnswersRate and _lessonActiveIds are only present when the certificate or its rule produced them. Treat their absence as normal.

The body carries no identity data: no name, email address or external identifier. To resolve the learner, call the public API with the award _id: GET /v1/certificates/{CERTIFICATE_ID} returns the same award with the learner's email, login and externalId. To catch up on awards without webhooks, GET /v1/certificates?updatedSince=... lists what changed since a date.

See Payload Examples for handler examples.

Delivery

• One call per award and per subscribed endpoint. Ten learners certified on the same day make ten calls.
• No automatic retry. A failed call (network error, timeout or non-2xx response) is not sent again. Use GET /v1/certificates?updatedSince=... to reconcile what you may have missed.
• Timeout. Beedeez waits 5 seconds for your response.
• Ordering. Calls go through a queue and may arrive out of order. Use creationDate and updatedAt to order awards.
• Duplicates. The same award can be sent twice, for example once on award and once on expiry. Make your handler idempotent on _id and expiryReminderSent.

Testing

1. Create a certificate on a test account, subscribe an endpoint to certificate_completed and have a test learner meet its rule.
2. Check that your endpoint receives the award and returns a 2xx response within 5 seconds.
3. To test the expiry path, use a capsule certificate with a short validity period and the expiry reminder enabled, then wait for the hourly job after the expiry date.

Next steps

• Payload Examples: handler code for the real payload
• Authentication: the options available to secure your endpoint
• Configuration Guide: setting up an endpoint