Audit Webhook Connector

Descope's Audit Webhook Connector allows Descopers to stream audit logs to their own API.

1. Deploy an API using a chosen service

Deploy an API to a service of your choice that accepts HTTP requests. This API will be used to receive the audit logs from Descope.

app/api/audit/route.tsx

export async function POST(request: Request) {
    const body = await request.json();
 
    // Handle audit logs
 
    return new Response(JSON.stringify(body), {
        headers: { 'content-type': 'application/json' },
    });
}

2. Configuring the Webhook Audit Connector

Navigate to the Descope's Audit Webhook Connector configuration page and fill in the required parameters:

Connector Name: Provide a unique name for your connector. This assists in distinguishing it, especially when multiple connectors are derived from the same template.
Connector Description: Briefly explain the purpose of this connector.
Base URL: Input the API URL where you'd like to send audit events to. This should start with either http:// or https://. Use the URL from Step 1.
Authentication Type: Descope supports various methods to authenticate with your service. Choose the method that suits your API:
- Bearer Token: Used for access keys such as JWTs.
- API Key: This usually involves a key-value pair.
- Basic Authentication: The traditional username and password method.
- None: Select this if your API doesn't require any authentication.
Headers (Optional): Some APIs need specific headers, usually key-value pairs, to provide more details about the impending action.
HMAC Secret (Optional): HMAC is a symmetric key method for message signing. The provided secret will be used to sign the payload. The outcome signature will be sent in the x-descope-webhook-s256 header. The recipient service should use this secret to validate the payload's integrity and authenticity by verifying the supplied signature.
Trust Any Certificate: By default, this option is turned off. If enabled, the client will overlook any certificate errors. While convenient for testing, it's crucial to remember that this is an insecure choice for production.

3. View Audit Logs

Once you've configured the Audit Webhook Connector, your events will be sent to the API you specified. You can view the audit logs in the Audit page, which should match the events you receive in your API.

Use Cases

Roles Revoked From A User

As a security best practice, monitoring changes in the association of roles to users is crucial. As the identity provider, Descope can provide the role name as part of the "UserModified" audit event.

{
    "Change": {
        "removed_multi_tenant_roles": {
            "T2lTcqSm7f5GD8lRwCyo4aHvC6wo": [
                {
                    "id": "ROL2lKYLkbHroW5IntCAYTWPX86rRs",
                    "name": "test1"
                }
            ]
        }
    },
    "browser": "Chrome",
    "correlation_id": "2nQJ0PEyu5EHrMJChqNgPC4AeVp",
    "device": "Desktop",
    "os": "macOS",
    "osVersion": "10.15.7"
    ...
}

In this example the role name "test1" was removed from the user.

Was this helpful?