Using Authsignal's webhooks

​

Supported events

The following challenge lifecycle events allow you to send SMS, email and push notifications via your own provider.

• email.created
• sms.created
• push.created

The following authenticator lifecycle 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 challenge lifecycle 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 authenticator lifecycle 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_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.

​

Expected responses and retry behavior

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

​

Challenge lifecycle webhooks

Challenge lifecycle 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.

​

Authenticator lifecycle webhooks

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

​

Next steps

• Event schema reference docs