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.

The authenticator challenge webhook is used to send SMS, email, and push notifications using a custom provider, as opposed to the providers supported by Authsignal natively.

​
Delivery behavior

Webhooks expect a 200 OK response for successful requests. Authenticator challenge webhooks are synchronous and the upstream request will fail for non-200 responses. For example, if you have configured a webhook to handle the sending of email OTPs, when a challenge is triggered and the webhook returns a non-200 response, the API will return an error response. An appropriate message should be displayed to the user when using our SDKs or APIs directly so that the user may trigger a retry via the UI. This is automatically handled in the pre-built UI.

​
Configuration

To configure webhook URLs for authenticator challenge events navigate to the settings for the relevant authenticator in the Authsignal Portal. Webhooks can be configured for the SMS OTP authenticator, Email OTP and Magic Link authenticators, and the Push authenticator.

​
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

​
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.
​
locale
string
The locale of the user who requested the magic link.
This is only present if the locale was captured when tracking an action or set on the user via update user.
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",
    "locale": "en"
  }
}

​
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.
​
locale
string
The locale of the user who requested the email OTP.
This is only present if the locale was captured when tracking an action or set on the user via update user.
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",
    "locale": "en"
  }
}

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

​
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.
​
locale
string
The locale of the user who requested the SMS code.
This is only present if the locale was captured when tracking an action or set on the user via update user.
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",
    "locale": "en"
  }
}

​
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