Authsignal events are defined by two parts - the events metadata, and the event-specific data.

All Authsignal events’ metadata is the same, and the event-specific data is unique to each event.

Event metadata

id
string

A unique identifier for the event.

source
string

The source of the event. This is always https://authsignal.com.

time
string

The time the event was created in ISO 8601 format.

type
string

The type of the event. Each type has a different schema for the data field.

version
string

The version of the event.

tenantId
string

The ID of the tenant that the event is intended for.

data
object

The event-specific data. See below for the schema of the data field for each event type.

Event metadata example

{
  "version": 1,
  "id": "00000000-0000-0000-0000-000000000000",
  "source": "https://authsignal.com",
  "time": "2024-01-01T01:23:45.678Z",
  "tenantId": "dddddddd-dddd-dddd-dddd-dddddddddddd",
  "type": "authenticator.created",
  "data": {
    ...
  }
}

Event data

Authenticator webhooks

to
string

The email address the magic link should be delivered to.

url
string

The URL of the magic link.

userId
string

The ID of the user the magic link is for.

userAgent
string

The user agent of the user who requested the magic link.

idempotencyKey
string

The idempotency key of the request that created the magic link.

timezone
object

The timezone of the user who requested the magic link.

ipAddress
object

The IP address of the user who requested the magic link.

actionCode
object

The action code of the track request that created the magic link.

type: email.created
{
  "version": 1,
  "id": "00000000-0000-0000-0000-000000000000",
  "source": "https://authsignal.com",
  "time": "2024-01-01T01:23:45.678Z",
  "tenantId": "dddddddd-dddd-dddd-dddd-dddddddddddd",
  "type": "email.created",
  "data": {
    "to": "example@gmail.com",
    "url": "https://mfa.authsignal.com/api/verify-magic-link?token=...",
    "userId": "11111111-1111-1111-1111-111111111111",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/527.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3",
    "idempotencyKey": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "timezone": "Europe/London",
    "ipAddress": "12.34.56.78",
    "actionCode": "sign-in"
  }
}

Email OTP

to
string

The email address the magic link should be delivered to.

code
string

The email OTP code.

userId
string

The ID of the user the email OTP code is for.

userAgent
string

The user agent of the user who requested the email OTP.

idempotencyKey
string

The idempotency key of the request that created the email OTP.

timezone
object

The timezone of the user who requested the email OTP.

ipAddress
object

The IP address of the user who requested the email OTP.

actionCode
object

The action code of the track request that created the email OTP.

type: email.created
{
  "version": 1,
  "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
  "source": "https://authsignal.com",
  "time": "2025-01-01T02:34:56.789Z",
  "tenantId": "dddddddd-dddd-dddd-dddd-dddddddddddd",
  "type": "email.created",
  "data": {
    "to": "example@gmail.com",
    "code": "123456",
    "userId": "11111111-1111-1111-1111-111111111111",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/527.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3",
    "idempotencyKey": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "timezone": "Europe/London",
    "ipAddress": "12.34.56.78",
    "actionCode": "sign-in"
  }
}

Push

challengeId
string

The challenge ID to be completed using push notification.

userId
string

The ID of the user the push challenge is for.

userAgent
string

The user agent of the user who requested the push notification.

idempotencyKey
string

The idempotency key of the request that created the push notification.

timezone
object

The timezone of the user who requested the push notification.

ipAddress
object

The IP address of the user who requested the push notification.

actionCode
object

The action code of the track request that created the push notification.

type: push.created
{
  "version": 1,
  "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
  "source": "https://authsignal.com",
  "time": "2025-01-01T02:34:56.789Z",
  "tenantId": "dddddddd-dddd-dddd-dddd-dddddddddddd",
  "type": "push.created",
  "data": {
    "challengeId": "61b5b44bea582c5f2c7e2c93f1f41d7d8f8e9fba8582a319be6a3aee696b018cc59f7d043acaaabab705c6d2b93ea1ef",
    "userId": "11111111-1111-1111-1111-111111111111",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/527.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3",
    "idempotencyKey": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "timezone": "Europe/London",
    "ipAddress": "12.34.56.78",
    "actionCode": "sign-in"
  }
}

SMS

to
string

The phone number the SMS should be delivered to (E.164 format).

code
string

The SMS code.

userId
string

The ID of the user the SMS code is for.

idempotencyKey
string

The idempotency key of the request that created the SMS code.

actionCode
object

The action code of the track request that created the SMS code.

type: sms.created
{
  "version": 1,
  "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
  "source": "https://authsignal.com",
  "time": "2025-01-01T02:34:56.789Z",
  "tenantId": "dddddddd-dddd-dddd-dddd-dddddddddddd",
  "type": "sms.created",
  "data": {
    "to": "+123456789",
    "code": "987654",
    "userId": "11111111-1111-1111-1111-111111111111",
    "idempotencyKey": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "actionCode": "sign-in"
  }
}

Event webhooks

Authenticator created

userId
string

The ID of the user that the authenticator was created for.

verificationMethod
string

The verification method of the authenticator that was created.

createdAt
string

The time the authenticator was created in ISO 8601 format.

userAuthenticatorId
object

A uniquie ID for the user authenticator that was created.

type: authenticator.created
{
  "version": 1,
  "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
  "source": "https://authsignal.com",
  "time": "2024-01-01T01:23:45.678Z",
  "tenantId": "dddddddd-dddd-dddd-dddd-dddddddddddd",
  "type": "authenticator.created",
  "data": {
    "userId": "11111111-1111-1111-1111-111111111111",
    "verificationMethod": "EMAIL_MAGIC_LINK",
    "createdAt": "2024-01-01T01:23:45.678Z",
    "userAuthenticatorId": "cccccccc-cccc-cccc-cccc-cccccccccccc"
  }
}

Authenticator deleted

userId
string

The ID of the user that the authenticator was deleted for.

verificationMethod
string

The verification method of the authenticator that was deleted.

createdAt
string

The time the authenticator was created in ISO 8601 format.

deletedAt
string

The time the authenticator was deleted in ISO 8601 format.

userAuthenticatorId
object

A uniquie ID for the user authenticator that was deleted.

type: authenticator.deleted
{
  "version": 1,
  "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
  "source": "https://authsignal.com",
  "time": "2025-01-01T02:34:56.789Z",
  "tenantId": "dddddddd-dddd-dddd-dddd-dddddddddddd",
  "type": "authenticator.deleted",
  "data": {
    "userId": "11111111-1111-1111-1111-111111111111",
    "verificationMethod": "EMAIL_MAGIC_LINK",
    "createdAt": "2024-01-01T01:23:45.678Z",
    "deletedAt": "2025-01-01T02:34:56.789Z",
    "userAuthenticatorId": "cccccccc-cccc-cccc-cccc-cccccccccccc"
  }
}