Skip to main content

​
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 post-verification action events are sent when an action reaches a terminal state and postVerificationWebhookUrl is configured on the action configuration.
  • action.updated
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 post-verification action events, set postVerificationWebhookUrl 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, post-verification action 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.

​
Post-verification action webhooks

Post-verification action webhooks are best-effort and does not impact the result of the action. The configured webhook should return a 200 success response.

​
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