API and webhooks

Duration25 minLevelAdvancedOfferModule Intégration

Objectives

• I know how to declare a webhook endpoint and choose its events
• I know the purpose of the signature secret and when to regenerate it
• I know how to activate the API and create a key with only the necessary rights
• I know how to interpret a 401 or 403 error

0 / 4 objectives achieved — check them off as you go through the lesson.

Why it's useful

These are the two sides of the same integration. Webhooks push information out: your SIEM, your HR tool, or your messaging system are notified as soon as a user is created or logs in. The API brings it in: a script or an external tool creates users, configures applications, or reads the audit log without going through the portal.

Your turn

To test without a server, use an online webhook reception service that provides you with a temporary URL.

Webhooks

1. Go to Configuration, tab Webhooks. → API and Webhooks
2. Click on Add an endpoint, enter the destination URL and select one or more events.
3. Trigger one of the chosen events (for example, create a test user if you selected user creation): it arrives via HTTP POST at your URL.
4. Find the signature secret displayed at the top of the tab. Your receiver uses it to verify the HMAC-SHA256 signature of each event.

API

1. In the API tab, toggle the Enable API switch.
2. Click on Create an API key, name it after what will use it (for example, "Onboarding Script"), then set its rights resource by resource: None, Read, or Read and write.
3. Copy the key immediately: it is only displayed once.
4. Open the interactive documentation with Open VaultysHub API documentation and call a read endpoint with your key.
5. In the ⋮ menu of the key, try Edit, then Revoke the key at the end of the exercise.

One key per integration

One key per use, with the minimum rights: you can revoke one without cutting off the others, and the audit log attributes each modification to the key name.

caution

A key with the right Applications: read gives access to client secrets of applications. Keep it like an administrator password.

Check your knowledge

1You regenerate the signature secret of the webhooks. What happens?

2You have lost an API key. What to do?

3A request receives the error 403 'Missing scope members:write'. Why?

To remember

• Webhooks send events to your systems, signed in HMAC-SHA256.
• The API is disabled by default; each key has a name and rights per resource.
• A key is only displayed once: if lost, it is revoked and replaced.

Next lesson: An AI assistant for administration