Skip to main content

Set up webhooks

Set up event-based notifications so third-party applications can react to key events in SecureAuth Connect in real time, instead of polling an API. When a subscribed event occurs, the platform sends an HTTP request to the URL you register. Developers can also manage webhooks through the Webhook CRUD APIs.

Use cases​

Use webhooks to drive downstream actions from platform events:

  • Keep external systems in sync – Deprovision a user in your CRM or downstream application when user.deleted fires, or create a record when user.created fires.
  • Centralize audit logging – Forward events to a SIEM or logging pipeline for security monitoring and compliance.
  • Open Banking and CDR notifications – Notify downstream systems when a consent is created, revoked, or rejected.
  • Trigger workflows – Start a workflow in response to sign-in, MFA, or authorization events.

Create a webhook for event-based notifications​

  1. In the target workspace, from the left sidebar, go to Extensions > Webhooks.

  2. Click Create Webhook and provide the following details:

    • URL – The endpoint to send notifications to (for example, a logging endpoint).
    • Subscribed events – Choose the events that trigger the notification. The available events depend on the server type (see Available events).

  3. Click Create to confirm. When prompted, copy the API key.

    The API key is sent with outbound SecureAuth requests and can secure the target server.

    Result: The webhook is now active, and event-based notifications trigger in this workspace.

    To disable certificate validation for SecureAuth requests, enable Developer mode.

Available events​

The events you can subscribe to depend on the server type of the authorization server where you create the webhook. The Subscribed events list shows only the events available for that server. Server types include workspace, organization, admin, and system.

CategoryExample eventsTypically available on
User lifecycleuser.created, user.updated, user.deleted, user.authenticatedWorkspace, organization, admin, system
Groupsgroup.created, group.updated, group.deleted, plus events when a user is added to or removed from a groupWorkspace, organization, admin, system
Credentials and MFAcredential.created, credential.updated, otp.sent, otp.accepted, totp.reset_completed, webauthn.add_completedWorkspace, organization, admin, system
Passwordspassword.updated, password.requested, password.confirmedWorkspace, organization, admin, system
Tokens and authorizationaccess_token.issued, authorization_code.issued, scopes.granted, saml_assertion.issuedWorkspace, organization, admin, system
Sign-inlogin.attempted, login.accepted, login.failedWorkspace, organization, admin, system
Consents (Open Banking, CDR, FDX)consent.created, consent.accepted, consent.rejected, consent.revokedWorkspace and organization, on Open Banking, CDR, and FDX profiles
Dynamic client registrationdcr.created, dcr.rejectedWorkspace, organization
Organizationsorganization.created, organization.updated, organization.deletedWorkspace, organization, admin, system
Applications and configurationclient.created, schema.created, pool.created, service.created, server.created, role.grantedAdmin
note

The user.deleted event is available at the workspace and organization levels, in addition to admin and system. This lets you react to a user deletion from the same workspace or organization where it occurs.

Event identifiers use a subject.action form (for example, user.deleted). The webhook payload delivers the matching field in subject_action form (for example, user_deleted).

Hardening​

Each webhook invocation contains an X-API-Key HTTP header with the unique Webhook API Key provided in the previous section. Configure your logging solution to validate this key and accept only requests with the correct value.

Here's an example of a minimal Nginx server that performs this check:

server {
    listen 80;
    server_name <public url of the logging solution>;

    location / {
        if ($http_x_api_key != '<webhook api key>') {
            return 403;
        }

        proxy_pass http://<backend url of the logging solution>;
    }
}

This ensures that only authorized webhook requests reach your logging solution.

See also​