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.

   SecureAuth sends the API key in the X-Api-Key header of every webhook request, so your endpoint can check that a request comes from this webhook. See Secure the receiving endpoint.

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

   Developer mode turns off TLS certificate verification for webhook requests. See Secure the receiving endpoint.

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.

Category	Example events	Typically available on
User lifecycle	user.created, user.updated, user.deleted, user.authenticated	Workspace, organization, admin, system
Groups	group.created, group.updated, group.deleted, plus events when a user is added to or removed from a group	Workspace, organization, admin, system
Credentials and MFA	credential.created, credential.updated, otp.sent, otp.accepted, totp.reset_completed, webauthn.add_completed	Workspace, organization, admin, system
Passwords	password.updated, password.requested, password.confirmed	Workspace, organization, admin, system
Tokens and authorization	access_token.issued, authorization_code.issued, scopes.granted, saml_assertion.issued	Workspace, organization, admin, system
Sign-in	login.attempted, login.accepted, login.failed	Workspace, organization, admin, system
Consents (Open Banking, CDR, FDX)	consent.created, consent.accepted, consent.rejected, consent.revoked	Workspace and organization, on Open Banking, CDR, and FDX profiles
Dynamic client registration	dcr.created, dcr.rejected	Workspace, organization
Organizations	organization.created, organization.updated, organization.deleted	Workspace, organization, admin, system
Applications and configuration	client.created, schema.created, pool.created, service.created, server.created, role.granted	Admin

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).

What a webhook delivers

Each webhook request has a JSON body with an audit_events array. A single request can carry several events.

{
  "audit_events": [
    {
      "tenant_id": "...",
      "server_id": "...",
      "event_id": "...",
      "timestamp": "...",
      "context": null,
      "event_subject": "...",
      "action": "...",
      "metadata": { ... },
      "payload": { ... }
    }
  ]
}

Each element of audit_events has the same shape as an item returned by the list audit events API, so the same parser works for both.

Field	Description
tenant_id	The tenant where the event occurred.
server_id	The workspace where the event occurred.
event_id	The unique identifier of the event.
timestamp	When the event occurred.
context	Not used. Always null.
event_subject	The entity the event is about, for example login.
action	What happened to the subject, for example accepted.
metadata	Request context and identifiers for the event. See Metadata fields.
payload	Event-specific data, under a single key named <subject>_<action>, for example login_accepted.

Metadata fields

metadata describes the request that caused the event and the users and configuration it involves. Most fields are omitted when they have no value for a given event.

Category	Fields	Description	Personal data
Request context	ip, country_code, city, latitude, longitude, user_agent, device_type, device_browser, device_os	Where the request came from and which device and browser sent it.	All fields
User and session identifiers	subject, idp_subject, user_id, affected_user_id, session_id, token_signature, actor_claims, may_act_claims	Who performed the action, who it affected, and the session or token involved.	All fields except token_signature
Risk and device	risk_loa, risk_id, high_risk, is_first_time_login, dbfp_fingerprint	The risk assessment for the request and the device fingerprint.	dbfp_fingerprint
Configuration identifiers	client_id, application_id, idp_id, idp_method, user_pool_id, identity_pool_id, affected_user_pool_id, organization_id, group_id, top_level_parent_id	The application, identity provider, pool, organization, or group involved.	None
Correlation	authorization_correlation_id, request_correlation_id, trace_id, result	Values that link related events, and the outcome of the request.	None

ip is the client IP address, resolved from request headers as described in Client IP address resolution.

Some event payloads also contain personal data. See Personal data in audit events.

Example: login accepted

The following request delivers one login accepted event. All values are fictitious. The workspace uses the hash subject format. For what each identifier holds, see Personal data in audit events.

{
  "audit_events": [
    {
      "tenant_id": "acme",
      "server_id": "customers",
      "event_id": "3f9c2a7e1b4d4c0e9a6f8b2d5e7c1a90",
      "timestamp": "2026-10-23T09:14:07.512Z",
      "context": null,
      "event_subject": "login",
      "action": "accepted",
      "metadata": {
        "ip": "203.0.113.42",
        "country_code": "PL",
        "city": "Warsaw",
        "latitude": 52.2297,
        "longitude": 21.0122,
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_5) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Safari/605.1.15",
        "device_type": "Desktop",
        "device_browser": "Safari",
        "device_os": "MacOS",
        "client_id": "c7d1e2f3a4b5c6d7e8f9",
        "subject": "b8f3c1d2e4a5f6071829a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8",
        "idp_subject": "9b2e7c4a-1f3d-4e8a-b6c5-2d7f9e1a3c48",
        "idp_id": "a1b2c3d4e5f60718",
        "idp_method": "identity_pool",
        "user_pool_id": "e5f6a7b8c9d0e1f2",
        "user_id": "9b2e7c4a-1f3d-4e8a-b6c5-2d7f9e1a3c48",
        "session_id": "4d6e8f0a2b4c6d8e0f2a4b6c8d0e2f4a",
        "authorization_correlation_id": "0a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
        "risk_loa": 0.82,
        "risk_id": "r-7f3e9a1c",
        "result": "success"
      },
      "payload": {
        "login_accepted": {
          "idp": { "id": "a1b2c3d4e5f60718", "name": "Customers", "method": "identity_pool" },
          "amr": ["pwd", "otp"]
        }
      }
    }
  ]
}

Secure the receiving endpoint

Webhook requests carry audit data, so accept them only over an encrypted connection and only from your webhook:

• Use HTTPS – The webhook URL must use https. SecureAuth verifies the endpoint's TLS certificate unless Developer mode is on. Developer mode skips certificate verification and is meant for testing only; turn it off for any endpoint that receives real data.
• Check the API key – Every request carries the webhook's API key in the X-Api-Key header. The key is a shared secret that identifies the sender. It doesn't sign the request body or prevent a captured request from being replayed, so rely on TLS for the integrity of the request. To rotate the key, set a new api_key when you update the webhook, then update the value your endpoint expects.
• Allow only SecureAuth addresses – Restrict the endpoint to the SecureAuth SaaS platform IP addresses.

Here's an example of a minimal Nginx server that terminates TLS and accepts only requests with the correct API key:

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

    ssl_certificate     <path to the certificate file>;
    ssl_certificate_key <path to the private key file>;

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

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

Delivery and retries

SecureAuth sends each webhook request as an HTTPS POST with the X-Api-Key and Content-Type: application/json headers.

• Success – A delivery succeeds when your endpoint returns a 2xx status code within 2 seconds. Any other status code, a redirect, or a timeout counts as a failure. Redirects are not followed.
• Batching – Several events can arrive in one request. When a request fails, the whole batch is retried.
• Retries – Failed deliveries are retried after 5 seconds, 30 seconds, and 1 minute, and then every 5 minutes, up to 20 attempts in total (about 80 minutes). After the last attempt the events are not sent again, but you can still retrieve them with the list audit events API within the audit event retention period.
• Failing endpoints – When an endpoint keeps failing, SecureAuth pauses deliveries to it for a short time before trying again.
• Duplicates – Delivery is at least once, so your endpoint can receive the same event more than once. Use event_id to detect duplicates.
• Ordering – Events can arrive in a different order than they occurred. Use timestamp to order them.

See also

• Audit Logs
• Personal data in audit events
• Getting business audit data using SecureAuth's audit events
• Integrating external logging solutions with SecureAuth audit events
• Extending SecureAuth capabilities