Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.authsignal.com/llms.txt

Use this file to discover all available pages before exploring further.

These can be used to send custom notifications to ensure that users are aware of all changes to the factors protecting their account. This can also be used to synchronize user details (such as Phone Number and Email Address) with other systems (e.g a Customer Relationship Management database).

​
Delivery behavior

Authenticator event webhooks expect a 200 OK response for successful requests. Authenticator event webhooks are asynchronous. For non-200 responses, the webhook will be retried up to 3 times after at least 30 seconds.

​
Configuration

To configure a webhook URL for authenticator events, navigate to the general settings for your tenant in the Authsignal Portal.

​
Verifying webhook events

It is critical to verify that incoming requests to your webhook have been sent by Authsignal and to reject any unauthorized requests. The recommended approach to verify webhook events is to use an Authsignal Server SDK to handle the incoming request. 
const authsignal = new Authsignal({ apiSecretKey: "YOUR_SERVER_API_SECRET_KEY" });

// Obtain raw request body and signature header
// For example using Express (https://expressjs.com/)
const payload = req.body;
const sig = req.headers["X-Signature-V2"];

const event = authsignal.webhook.constructEvent(payload, sig);
By passing the raw request body along with the X-Signature-V2 header to the SDK, it will verify that the request is valid and construct the event to be handled.
The Authsignal SDK requires the raw body of the request to verify the signature. If you’re using a framework, make sure it doesn’t manipulate the raw body as this will cause the signature verification to fail.

​
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 schema

​
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 unique ID for the user authenticator that was created.
​
email
string
The email address associated with the authenticator. Included for email OTP and magic link authenticators.
​
phoneNumber
string
The phone number associated with the authenticator. Included for SMS and WhatsApp authenticators.
​
credentialId
string
The passkey credential ID. Only included for passkey authenticators.
​
credentialPublicKey
string
The base64url-encoded public key of the passkey credential. Only included for passkey authenticators when includeCredentialPublicKey is enabled in webhook settings.
​
aaguid
string
The AAGUID of the authenticator that created the passkey. Only included for passkey authenticators.
​
credentialName
string
A display name for the passkey authenticator, such as the device or credential manager name. Only included for passkey authenticators.
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",
    "email": "jane.smith@authsignal.com"
  }
}

​
Authenticator updated

​
userId
string
required
The ID of the user that the authenticator was updated for.
​
verificationMethod
string
required
The verification method of the authenticator that was updated.
​
updatedAt
string
required
The time the authenticator was updated in ISO 8601 format.
​
userAuthenticatorId
string
required
A unique ID for the user authenticator that was updated.
​
previousSmsChannel
string
The last channel that was used to successfully complete an SMS OTP challenge. Either “DEFAULT” (regular SMS) or “WHATSAPP”.
​
email
string
The email address associated with the authenticator. Included for email OTP and magic link authenticators.
​
phoneNumber
string
The phone number associated with the authenticator. Included for SMS and WhatsApp authenticators.
​
credentialId
string
The passkey credential ID. Only included for passkey authenticators.
​
aaguid
string
The AAGUID of the authenticator that created the passkey. Only included for passkey authenticators.
​
credentialName
string
A display name for the passkey authenticator, such as the device or credential manager name. Only included for passkey authenticators.
type: authenticator.updated
{
  "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.updated",
  "data": {
    "userId": "11111111-1111-1111-1111-111111111111",
    "verificationMethod": "SMS",
    "updatedAt": "2024-01-01T01:23:45.678Z",
    "userAuthenticatorId": "cccccccc-cccc-cccc-cccc-cccccccccccc",
    "previousSmsChannel": "WHATSAPP",
    "phoneNumber": "+12345678901"
  }
}

​
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 unique ID for the user authenticator that was deleted.
​
email
string
The email address associated with the authenticator. Included for email OTP and magic link authenticators.
​
phoneNumber
string
The phone number associated with the authenticator. Included for SMS and WhatsApp authenticators.
​
credentialId
string
The passkey credential ID. Only included for passkey authenticators.
​
aaguid
string
The AAGUID of the authenticator that created the passkey. Only included for passkey authenticators.
​
credentialName
string
A display name for the passkey authenticator, such as the device or credential manager name. Only included for passkey authenticators.
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"
  }
}

​
IP address allow-listing

Authsignal will send webhooks originating from the following IP addresses:
RegionIP Addresses
US (Oregon)44.224.97.232
44.230.210.235
44.236.208.22
52.33.85.88
AU (Sydney)13.210.81.243
3.105.80.107
54.252.129.142
EU (Dublin)34.247.148.106
34.253.116.90
54.171.116.55
CA (Montreal)16.52.98.180
16.54.49.43
16.54.18.28