Webhooks
Enable real-time, event-driven notifications to keep your organisation aware of all the changes happening within the ecosystem. Remain synchronized and informed about critical updates, such as changes to organizations, APIs, certifications, and roles, without needing to constantly poll for information.
Webhooks provide organizations with real-time updates about ecosystem changes, ensuring they stay informed and responsive.
By automating notifications, webhooks eliminate the need for manual monitoring, significantly improving operational efficiency. Additionally, they offer integration flexibility, allowing organizations to adapt their systems dynamically to ecosystem updates and maintain seamless interaction with other participants.
You can subscribe an application or an authorization server to notifications from Raidiam.
To learn how to subscribe to events happening in your ecosystem, see the Subscribe to Events article.
Certain actions may result in multiple notifications being sent through the webhook.
For instance, suspending an application not only suspends the application itself but also disables any certificates and keys issued for it. Consequently, separate notifications are sent for each of these events, detailing the disabling of each certificate and key individually.
- Organisations: Notifications are triggered when an organisation is created, updated, or deleted in the directory. This ensures that any changes to organisational details, such as name, contact information, or status, are immediately communicated to relevant systems.
- Authorization Server: Changes to an organisation’s authorization server configuration—such as adding or removing an instance—are communicated through webhooks.
- Domain Claims: Notifications are sent when the domain claim for an organisation changes.
- Org Auth Domain Role Claim: When an organization requests or updates its role authorization within a domain, webhooks notify relevant parties.
- Authorization Server Certification: Webhooks are triggered when an organisation’s authorization server gains or loses a certification. These certifications verify compliance with ecosystem standards.
- API Resource: Changes to API resources, such as endpoints, versions, or supported operations, will trigger notifications.
- API Discovery Endpoint: Webhooks notify changes related to endpoints used for API discovery.
- Contacts: Notifications are sent when the contact details of an organisation, such as administrative or technical contacts, are added, updated, or removed.
- Software Authority Claim: Webhooks notify when a software authority claim is created or updated.
- Domain Role Authorization: Notifications are triggered when a role authorization within a domain is either granted or revoked for an organization.
- Organization or Application/Software Statements Certificate: Webhooks notify the issuance or revocation of digital certificates for organizations or their software. These certificates are critical for secure communications and authentication within the ecosystem.
- Application (Software Statement): A comprehensive set of webhook events is triggered for software statements. These include creation, updates, deletions, suspension, lifting of suspension, blocking, and unblocking.
- Organization’s Terms and Conditions: Webhooks are triggered when the process of signing terms and conditions begins. Notifications are also sent if there are changes in the status of the process, such as approval, rejection, or cancellation.
The webhook payloads are constructed following a "general-to-event" structure. For each triggered event, the entire structure of the changed resource is detailed within the response payload.
This design allows for the entire chain of context to be included in the payload, making it easier to interpret and act on notifications.
The event payload always consists of four fields:
- ApiResource - the identifier of the resource for which the event happened.
- UpdateTimestamp - the time at which the event happened.
- ResourcePayload - the payload (details) of the resource for which the event happened.
- Revision - a versioning mechanism that tracks changes or updates to the resource being notified.
For most up to date resource payload samples, always refer to Raidiam API documentation and the schema for the given resource.