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 Log events webhook can be used to send logs relating to actions and challenges to a custom destination. This allows later analysis using third party SIEM, data lakes, or custom tooling.

​
Delivery behavior

Webhooks expect a 200 OK response for successful requests. Events are sent in batches of up to 500 events. If event delivery fails, delivery will be periodically retried until success. Delivery is asynchronous, and will be delivered after a delay based on your tenant’s challenge token duration (typically 15 minutes). The webhook adheres to at-least-once delivery. This means that event delivery may be duplicated, and your webhook may need to de-duplicate events. Use the id in the metadata to de-duplicate events.

​
Configuration

To configure a webhook URL for log 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.

​
Delivery schema

Batches of events are sent as a list of event records, with up to 500 events in one batch: 
{
  "records": [
    { "type": "action.log_created",    "record": { } },
    { "type": "challenge.log_created", "record": { } }
  ]
}

​
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

​
Action log created

​
tenantId
string
required
The ID of the tenant that the action occurred within.
​
userId
string
required
The ID of the user that the action was triggered by.
​
actionCode
string
required
The action being evaluated (e.g. login, withdrawal).
​
idempotencyKey
string
required
Unique per action instance.
​
createdAt
string
required
When the action was first evaluated.
​
updatedAt
string
required
When the action record was last updated.
​
state
string
required
Final action state — e.g. ALLOW, BLOCK, CHALLENGE_REQUIRED, CHALLENGE_SUCCEEDED, CHALLENGE_FAILED, REVIEW_REQUIRED.
​
stateUpdatedAt
string
required
When state last changed.
​
outcome
string
required
The rule-engine decision — one of ALLOW, BLOCK, CHALLENGE, REVIEW. Immutable for the lifetime of the action.
​
verificationMethod
string
The method the user actually used to complete a challenge, if any (e.g. EMAIL_OTP, PASSKEY, SMS, AUTHENTICATOR_APP).
​
allowedVerificationMethods
string[]
The set of methods the user was offered for this challenge. Omitted if empty.
​
rules
object[]
Rules that fired during evaluation. Omitted if none.
​
priorityRuleId
string
The rule that drove the outcome, when multiple rules fired.
​
ipAddress
string
IP address of the request that initiated the action.
​
countryCode
string
Country resolved from the IP.
​
email
string
Email on file for the user at the time of the action.
​
phoneNumber
string
Phone number on file for the user at the time of the action.
​
deviceId
string
Opaque identifier for the device that initiated the action.
​
enrolledVerificationMethods
string[]
Verification methods the user had enrolled at the time of the action.
​
custom
object
Custom key/value data supplied by your application. Omitted if empty.
type: action.log_created
{
  "version": 1,
  "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
  "source": "https://authsignal.com",
  "time": "2026-04-22T01:08:05.197Z",
  "tenantId": "dddddddd-dddd-dddd-dddd-dddddddddddd",
  "type": "action.log_created",
  "record": {
    "tenantId": "dddddddd-dddd-dddd-dddd-dddddddddddd",
    "userId": "user_abc",
    "actionCode": "login",
    "idempotencyKey": "bb51e6b9-a7f8-4f03-8044-2940ae574236",
    "createdAt": "2026-04-22T01:08:05.197Z",
    "updatedAt": "2026-04-22T01:08:05.197Z",
    "state": "CHALLENGE_SUCCEEDED",
    "stateUpdatedAt": "2026-04-22T01:10:34.067Z",
    "outcome": "CHALLENGE",
    "verificationMethod": "EMAIL_OTP",
    "allowedVerificationMethods": ["PASSKEY", "EMAIL_OTP", "AUTHENTICATOR_APP"],
    "rules": [
      { "id": "40fcd205-5318-41d7-b225-3b6122b13654", "name": "challenge nz" }
    ],
    "priorityRuleId": "40fcd205-5318-41d7-b225-3b6122b13654",
    "ipAddress": "192.168.1.1",
    "countryCode": "NZ",
    "email": "alice@example.com",
    "phoneNumber": "+64221234567",
    "deviceId": "device_xyz",
    "enrolledVerificationMethods": ["AUTHENTICATOR_APP", "EMAIL_OTP"],
    "custom": { "plan": "pro" }
  }
}

​
Challenge log created

​
tenantId
string
required
The ID of the tenant that the action occurred within.
​
userId
string
required
The ID of the user that the action was triggered by.
​
actionCode
string
required
The action being evaluated (e.g. login, withdrawal).
​
idempotencyKey
string
required
Unique per action instance.
​
createdAt
string
required
When this challenge event occurred.
​
type
string
required
The event type.
​
verificationMethod
string
The verification method involved (e.g. EMAIL_OTP, SMS, PASSKEY).
​
email
string
Email address involved in the event (for email-channel events).
​
phoneNumber
string
Phone number involved in the event (for SMS/WhatsApp-channel events).
​
errorDescription
string
Human-readable error summary for *_FAILED events.
​
statusCode
string
Upstream HTTP status code for downstream-delivery failure events.
​
data
object
Additional structured fields. Omitted if empty.
type: challenge.log_created
{
  "version": 1,
  "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
  "source": "https://authsignal.com",
  "time": "2026-04-22T01:10:20.939Z",
  "tenantId": "dddddddd-dddd-dddd-dddd-dddddddddddd",
  "type": "challenge.log_created",
  "record": {
    "tenantId": "dddddddd-dddd-dddd-dddd-dddddddddddd",
    "userId": "user_abc",
    "actionCode": "login",
    "idempotencyKey": "bb51e6b9-a7f8-4f03-8044-2940ae574236",
    "createdAt": "2026-04-22T01:10:20.939Z",
    "type": "EMAIL_OTP_SENT",
    "verificationMethod": "EMAIL_OTP",
    "email": "alice@example.com"
  }
}

​
Challenge event types

A non-exhaustive list of the most commonly seen event types. Email OTP: EMAIL_OTP_SENT, EMAIL_OTP_CODE_VALID, EMAIL_OTP_INVALID_OR_EXPIRED, EMAIL_OTP_MAX_ATTEMPTS_EXCEEDED, EMAIL_OTP_RATE_LIMIT_EXCEEDED, EMAIL_OTP_SEND_DOWNSTREAM_FAILED Email magic link: EMAIL_MAGIC_LINK_SENT, EMAIL_MAGIC_LINK_INVALID_OR_EXPIRED, EMAIL_MAGIC_LINK_RATE_LIMIT_EXCEEDED, EMAIL_MAGIC_LINK_SEND_DOWNSTREAM_FAILED SMS: SMS_SENT, SMS_DELIVERED, SMS_NOT_DELIVERED, SMS_CODE_VALID, SMS_CODE_INVALID_OR_EXPIRED, SMS_MAX_ATTEMPTS_EXCEEDED, SMS_RATE_LIMIT_EXCEEDED, SMS_SEND_DOWNSTREAM_FAILED WhatsApp: WHATSAPP_SENT, WHATSAPP_CODE_VALID, WHATSAPP_CODE_INVALID_OR_EXPIRED, WHATSAPP_MAX_ATTEMPTS_EXCEEDED, WHATSAPP_RATE_LIMIT_EXCEEDED, WHATSAPP_SEND_DOWNSTREAM_FAILED TOTP / authenticator app: TOTP_CODE_VALID, TOTP_CODE_INVALID_OR_EXPIRED, TOTP_MAX_ATTEMPTS_EXCEEDED Push: PUSH_SENT

​
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