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
required

A unique identifier for the event.

source
string
required

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

time
string
required

The time the event was created in ISO 8601 format.

type
string
required

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

version
string
required

The version of the event.

tenantId
string
required

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

data
object
required

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
required

The email address the magic link should be delivered to.

url
string
required

The URL of the magic link.

userId
string
required

The ID of the user the magic link is for.

idempotencyKey
string
required

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

actionCode
string
required

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

userAgent
string

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

This is only present if the user agent was captured when tracking an action.

timezone
string

The timezone of the user who requested the magic link.

This is only present if the IP address was captured when tracking an action.

ipAddress
string

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

This is only present if the IP address was captured when tracking an action.

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",
    "idempotencyKey": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "actionCode": "sign-in",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/527.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3",
    "timezone": "Europe/London",
    "ipAddress": "12.34.56.78"
  }
}

Email OTP

to
string
required

The email address the magic link should be delivered to.

code
string
required

The email OTP code.

userId
string
required

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

idempotencyKey
string
required

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

actionCode
string
required

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

userAgent
string

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

This is only present if the user agent was captured when tracking an action.

timezone
string

The timezone of the user who requested the email OTP.

This is only present if the IP address was captured when tracking an action.

ipAddress
string

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

This is only present if the IP address was captured when tracking an action.

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",
    "idempotencyKey": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "actionCode": "sign-in",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/527.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3",
    "timezone": "Europe/London",
    "ipAddress": "12.34.56.78"
  }
}

Push

challengeId
string
required

The challenge ID to be completed using push notification.

userId
string
required

The ID of the user the push challenge is for.

idempotencyKey
string
required

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

actionCode
string
required

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

userAgent
string

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

This is only present if the user agent was captured when tracking an action.

timezone
string

The timezone of the user who requested the push notification.

This is only present if the IP address was captured when tracking an action.

ipAddress
string

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

This is only present if the IP address was captured when tracking an action.

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",
    "idempotencyKey": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "actionCode": "sign-in",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/527.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3",
    "timezone": "Europe/London",
    "ipAddress": "12.34.56.78"
  }
}

SMS

to
string
required

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

code
string
required

The SMS code.

userId
string
required

The ID of the user the SMS code is for.

idempotencyKey
string
required

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

actionCode
string
required

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
required

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

verificationMethod
string
required

The verification method of the authenticator that was created.

createdAt
string
required

The time the authenticator was created in ISO 8601 format.

userAuthenticatorId
string
required

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
required

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

verificationMethod
string
required

The verification method of the authenticator that was deleted.

createdAt
string
required

The time the authenticator was created in ISO 8601 format.

deletedAt
string
required

The time the authenticator was deleted in ISO 8601 format.

userAuthenticatorId
string
required

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"
  }
}