API, webhooks and callbacks

This section covers the three ways Beedeez exchanges data with your own systems: the public API you call, the webhooks that call you, and the completion callback a third-party tool uses to report that a learner finished a capsule. Each has its own prerequisites and its own article.

The public API is a service of its own, separate from the rest of the platform: it answers on its own domain, api.developers.beedeez.com, and covers only what its reference describes. The calls the back-office and the app make to the Beedeez server are not part of it.

⚠️ The reference and the API are two different addresses. The OpenAPI reference is published at doc.developers.beedeez.com . api.developers.beedeez.com is the server your integration calls, and its root returns 404.

What has to be open on your account

Each mechanism depends on an option that no back-office screen switches on. Ask your Beedeez contact for the one you need.

• Public API: without its option, the Developers API sub-page does not appear under Configuration › Integrations, and no key can be generated.
• Webhooks: a separate option, with its own sub-page, Configuration › Integrations › Webhooks.
• Completion callback: no API key, but an external content source already configured.

⚠️ An option and a right are two different things. Opening the Configuration menu needs the Update customization right, and that right cannot be granted to a profile attached to a department. A missing Developers API entry therefore comes from the option, from the right, or from both: say which of the two you already have when you ask.

Which way the call goes

You call Beedeez: the public API, when you fetch data at the moment you need it, presenting a token obtained from your key. Beedeez calls you: webhooks, on a URL you declare, when an event occurs. A third party calls Beedeez: the completion callback, the one entry point in this section that needs no API key, since the token is in the URL.

Before starting any development

⚠️ Many needs phrased as “we need the API” are already covered by an existing connector, and the API is only worth the development if none of these three fits:

• Automating activity export to your SFTP: to receive a file of the activity on a regular basis.
• Which brick for which need: SSO, SCIM, HRIS file, Lucca: to create, update or deactivate accounts from your HRIS.
• External content sources: to surface content hosted elsewhere inside Beedeez.

Calling the API

• API keys: create the key, store it before closing the screen, revoke it the day you have to.
• API authentication: exchange the key for a token, and the mistakes that bring an integration down in production.
• API resources: what the API exposes, and where to read the current reference rather than a copy of it.

Being called by Beedeez

• Webhook events: to read before designing anything, because the list actually emitted is shorter than the configurable one.
• Configuring a webhook: declare the URL, pick the authentication mode, check the signature, hold the response deadline.

The two integrations apart

• Reporting completion from a third-party tool: when content is followed elsewhere and its completion has to come back into Beedeez.
• Persona: identity verification: when a certifying capsule requires proof of who is taking it, under a contract with Persona.

When an integration does not behave as expected, start with Common problems: integrations.