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.

​
Supported events

The following authenticator challenge events allow you to send SMS, email and push notifications via your own provider.
  • email.created
  • sms.created
  • push.created
The following action verification event is sent synchronously after a challenge is verified. The webhook can be used to trigger additional tasks. A non-2xx response blocks the challenge from succeeding and returns an error to the caller.
  • action.verify
The following authenticator events will be fired when a user adds, updates or removes an authenticator. These can be used to send custom notifications to ensure that users are aware of all changes to the factors protecting their account.
  • authenticator.created
  • authenticator.updated
  • authenticator.deleted

​
Configuring webhook urls

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. To configure a webhook URL for the action verification event, set verificationWebhookUrl on the relevant action configuration in the Authsignal Portal or via the Create Action Configuration and Update Action Configuration Management API endpoints. 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.

​
Expected responses and retry behavior

Webhooks expect a 200 OK response for successful requests. The behavior of non-200 responses differs between authenticator challenge events, action verification events, and authenticator events:

​
Authenticator challenge webhooks

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.

​
Action verification webhooks

The action verification webhook is synchronous. It is invoked when an action is about to transition to CHALLENGE_SUCCEEDED. A non-200 response or a timeout is treated as an error. The user can retry by re-running the verification. There are no automatic retries.

​
Authenticator event webhooks

Authenticator event webhooks are asynchronous. For non-200 responses, the webhook will be retried up to 3 times after at least 30 seconds.

​
IP address whitelisting

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

​
Next steps