Editing Events

Modify existing event configuration with backwards compatibility.

Editing Events

Once you’ve successfully configured Audit Logs in the WorkOS Dashboard and begun emitting events, how do you go about modifying an event schema without breaking your existing integrations? This is where versioning comes into place. When you make a modification to an existing schema it will create a new version rather than overwriting the existing schema.

The reason for this behavior is to ensure backwards compatibility. Schema configuration is immutable to prevent you from accidentally making changes that are incompatible with events that are already being emitted from your application. Rather you must first create a new version of the schema, and then explicitly emit events for that version leveraging the event version field.

Creating a new event version

In the WorkOS Dashboard, open Audit Logs and select the event whose schema you would like to modify.

You can edit both the targets associated with the event and the metadata JSON schema. Select Save as new version to create a new version of the event schema.

A screenshot showing the “Save as new version” button in the schema editor in the WorkOS Dashboard.

Emitting event with version

Now that a schema exists with a new version, the version field must be provided when emitting an event so that WorkOS knows which version to use for validation.

Emit event

JavaScript

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

await workos.auditLogs.createEvent('org_01EHWNCE74X7JSDV0X3SZ3KJNY', {
  action: 'user.signed_in',
  version: 2,
  occurredAt: new Date(),
  actor: {
    type: 'user',
    id: 'user_01GBNJC3MX9ZZJW1FSTF4C5938',
  },
  targets: [
    {
      type: 'team',
      id: 'team_01GBNJD4MKHVKJGEWK42JNMBGS',
    },
    {
      type: 'resource',
      id: 'resource_01GBTAX2J37BAMB2D8GYDR2CC6',
    },
  ],
  context: {
    location: '123.123.123.123',
    userAgent: 'Chrome/104.0.0.0',
  },
});

 require "workos"

workos = WorkOS::Client.new(api_key: "sk_example_123456789")

event = {
  action: "user.signed_in",
  occurred_at: "2022-09-08T19:46:03.435Z",
  version: 2,
  actor: {
    id: "user_01GBNJC3MX9ZZJW1FSTF4C5938",
    type: "user"
  },
  targets: [
    {
      id: "team_01GBNJD4MKHVKJGEWK42JNMBGS",
      type: "team"
    },
    {
      id: "resource_01GBTAX2J37BAMB2D8GYDR2CC6",
      type: "resource"
    }
  ],
  context: {
    location: "123.123.123.123",
    user_agent: "Chrome/104.0.0.0"
  }
}

workos.audit_logs.create_event(
  organization_id: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
  event: event
)

 import datetime

from workos import WorkOSClient
from workos.types.audit_logs import AuditLogEvent

workos_client = WorkOSClient(
    api_key="sk_example_123456789", client_id="client_123456789"
)

organization_id = "org_01EHWNCE74X7JSDV0X3SZ3KJNY"
event: AuditLogEvent = {
    "action": "user.signed_in",
    "version": 2,  # version provided
    "occurred_at": datetime.datetime.now(tz=datetime.UTC).isoformat(),
    "actor": {
        "type": "user",
        "id": "user_01GBNJC3MX9ZZJW1FSTF4C5938",
        "metadata": {
            "role": "admin",
        },
    },
    "targets": [
        {
            "type": "team",
            "id": "team_01GBNJD4MKHVKJGEWK42JNMBGS",
            "metadata": {
                "owner": "user_01GBTCQ2MZG9C87R7NAQZZS7M6",
            },
        },
    ],
    "context": {
        "location": "123.123.123.123",
        "user_agent": "Chrome/104.0.0.0",
    },
    "metadata": {
        "environment": "staging",
    },
}

workos_client.audit_logs.create_event(organization_id=organization_id, event=event)

 package main

import (
	"context"
	workos "github.com/workos/workos-go/v10"
	"time"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.AuditLogs().CreateEvent(context.Background(), &workos.AuditLogsCreateEventParams{
		OrganizationID: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
		Event: &workos.AuditLogEvent{
			Action:     "user.signed_in",
			Version:    workos.Int(2),
			OccurredAt: time.Now().Format(time.RFC3339),
			Actor: &workos.AuditLogEventActor{
				ID:   "user_01GBNJC3MX9ZZJW1FSTF4C5938",
				Type: "user",
			},
			Targets: []*workos.AuditLogEventTarget{
				{
					ID:   "team_01GBNJD4MKHVKJGEWK42JNMBGS",
					Type: "team",
				},
			},
			Context: &workos.AuditLogEventContext{
				Location:  "123.123.123.123",
				UserAgent: workos.String("Chrome/104.0.0.0"),
			},
		},
	})
	if err != nil {
		// Handle the error...
	}
}

 <?php

$workos = new \WorkOS\WorkOS();

$auditLogEvent = new \WorkOS\Resource\AuditLogEvent(
    action: "user.signed_in",
    occurredAt: new \DateTimeImmutable(),
    version: 2,
    actor: new \WorkOS\Resource\AuditLogEventActor(
        id: "user_01GBNJC3MX9ZZJW1FSTF4C5938",
        type: "user",
    ),
    targets: [
        new \WorkOS\Resource\AuditLogEventTarget(
            id: "team_01GBNJD4MKHVKJGEWK42JNMBGS",
            type: "team",
        ),
        new \WorkOS\Resource\AuditLogEventTarget(
            id: "resource_01GBTAX2J37BAMB2D8GYDR2CC6",
            type: "resource",
        ),
    ],
    context: new \WorkOS\Resource\AuditLogEventContext(
        location: "123.123.123.123",
        userAgent: "Chrome/104.0.0.0",
    ),
);

$workos
    ->auditLogs()
    ->createEvent(
        organizationId: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
        event: $auditLogEvent,
    );

 <?php

use WorkOS\Laravel\Facades\WorkOS;
use WorkOS\Resource\AuditLogEvent;
use WorkOS\Resource\AuditLogEventActor;
use WorkOS\Resource\AuditLogEventContext;
use WorkOS\Resource\AuditLogEventTarget;

$auditLogEvent = new AuditLogEvent(
    action: "user.signed_in",
    occurredAt: new \DateTimeImmutable(),
    version: 2,
    actor: new AuditLogEventActor(
        id: "user_01GBNJC3MX9ZZJW1FSTF4C5938",
        type: "user",
    ),
    targets: [
        new AuditLogEventTarget(
            id: "team_01GBNJD4MKHVKJGEWK42JNMBGS",
            type: "team",
        ),
        new AuditLogEventTarget(
            id: "resource_01GBTAX2J37BAMB2D8GYDR2CC6",
            type: "resource",
        ),
    ],
    context: new AuditLogEventContext(
        location: "123.123.123.123",
        userAgent: "Chrome/104.0.0.0",
    ),
);

WorkOS::auditLogs()->createEvent(
    organizationId: "org_01EHWNCE74X7JSDV0X3SZ3KJNY",
    event: $auditLogEvent,
);

 import com.workos.WorkOS;
import com.workos.auditlogs.AuditLogsApi.CreateAuditLogEventOptions;
import java.util.Date;

WorkOS workos = new WorkOS("sk_example_123456789");

CreateAuditLogEventOptions options =
    CreateAuditLogEventOptions.builder()
        .action("user.signed_in")
        .version(2)
        .occurredAt(new Date())
        .actor("user_01GBNJC3MX9ZZJW1FSTF4C5938", "user")
        .target("team_01GBNJD4MKHVKJGEWK42JNMBGS", "team")
        .target("resource_01GBTAX2J37BAMB2D8GYDR2CC6", "resource")
        .context("123.123.123.123", "Chrome/104.0.0.0")
        .build();

workos.auditLogs.createEvent("org_01EHWNCE74X7JSDV0X3SZ3KJNY", options);

 WorkOS.SetApiKey("sk_example_123456789");

var auditLogsService = new AuditLogsService();

var auditLogEvent = new AuditLogEvent {
    Action = "user.signed_in",
    OccurredAt = DateTime.Now,
    Version = 2,
    Actor =
        new AuditLogEventActor {
            Id = "user_01GBNJC3MX9ZZJW1FSTF4C5938",
            Type = "user",
        },
    Targets =
        new List<AuditLogEventTarget>() {
            new AuditLogEventTarget {
                Id = "team_01GBNJD4MKHVKJGEWK42JNMBGS",
                Type = "team",
            },
            new AuditLogEventTarget {
                Id = "resource_01GBTAX2J37BAMB2D8GYDR2CC6",
                Type = "resource",
            },
        },
    Context =
        new AuditLogEventContext {
            Location = "123.123.123.123",
            UserAgent = "Chrome/104.0.0.0",
        },
};

var options =
    new CreateAuditLogEventOptions() { OrganizationId = "org_01EHWNCE74X7JSDV0X3SZ3KJNY", Event = auditLogEvent };

auditLogsService.CreateEvent(options);