Webhooks
Authsignal webhooks enable you to receive notifications via your POST endpoint for various events that occur in real-time.
Supported events
The following webhook events are available to use:
email.created
push.created
sms.created
Verify a signed webhook
Signed webhooks ensure the data's authenticity and integrity between systems by creating a digital signature with a secret key. The signature is sent alongside the data on the webhook, and the recipient verifies it with the same secret key to prevent malicious attacks.
Failing to verify the request leaves your app vulnerable to various security threats.
The secret key used for HMAC-SHA256
signature generation is your Authsignal secret key, which can be found in Settings -> API Keys -> Secret key in Authsignal's admin portal.
Webhook setup:
Create a POST endpoint on your server that listens for incoming webhook requests.
Add this endpoint's URL to your authenticator's webhook configuration settings in Authsignal's admin portal.
Verification steps:
In your webhook function, retrieve the x-signature, content-type and x-timestamp headers from the incoming request.
Construct the message to be signed by concatenating the following with a new line character as the separator (you can use the example code's messageToSign variable as a reference):
- HTTP method
- Your webhook URL
- The
content-type
andx-timestamp
request headers. These must be converted to title case as shown. - The request body.
Compute the
HMAC-SHA256
signature of the message using your secret key in Authsignal's admin portal.Compare the
x-timestamp
(lowercase intended) value in the header with the current time and check that it is within a reasonable range e.g. less than 10 minutes.Compare the computed signature with the incoming signature. If they match, the request is authenticated and can be processed; otherwise, the request is not authentic and should be rejected.
- Node.js
const secretKey = process.env["AUTHSIGNAL_SECRET_KEY"];
// Retrieve the x-signature header from the incoming request
const signature = req.headers["x-signature"];
const requestHeaders = {
"Content-Type": req.headers["content-type"],
"X-Timestamp": req.headers["x-timestamp"],
};
const webhookUrl = "your webhook url"; //e.g https://webhook.site/verify
const messageToSign = `${req.method}\n${webhookUrl}\n${JSON.stringify(requestHeaders)}\n${JSON.stringify(req.body)}`;
// Compute the HMAC-SHA256 signature of the message
const computedSignature = createHmac("sha256", secretKey).update(messageToSign).digest("base64");
// Compare the computed signature with the incoming signature
if (computedSignature === signature) {
// Request is authentic, process it accordingly
} else {
// Request is not authentic, reject it
}
Example payloads
{
"version": 1,
"type": "email.created",
"data": {
"to": "example@gmail.com",
"url": "https://mfa.authsignal.com/api/verify-magic-link?token=...",
"userId": "74156d35-3d0d-4303-90ee-e0ba2bcb9182",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/527.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3",
"idempotencyKey": "31926ae8-44a3-4c07-9ca3-c648084ff313",
"timezone": "Europe/Moscow",
"ipAddress": "95.31.18.119",
"actionCode": "sign-in"
}
}
{
"version": 1,
"type": "email.created",
"data": {
"to": "example@gmail.com",
"code": "123456",
"userId": "74156d35-3d0d-4303-90ee-e0ba2bcb9182",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/527.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3",
"idempotencyKey": "31926ae8-44a3-4c07-9ca3-c648084ff313",
"timezone": "Europe/Moscow",
"ipAddress": "95.31.18.119",
"actionCode": "sign-in"
}
}
{
"version": 1,
"type": "push.created",
"data": {
"challengeId": "61b5b44bea582c5f2c7e2c93f1f41d7d8f8e9fba8582a319be6a3aee696b018cc59f7d043acaaabab705c6d2b93ea1ef",
"userId": "74156d35-3d0d-4303-90ee-e0ba2bcb9182",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/527.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3",
"idempotencyKey": "f3025f69-03a1-4bb5-9823-8a2ff3e349ec",
"ipAddress": "95.31.18.119",
"timezone": "Europe/Moscow",
"actionCode": "sign-in"
}
}
{
"version": 1,
"type": "sms.created",
"data": {
"code": "370248",
"to": "+1202123445",
"userId": "ee18eabc-ee3b-4212-ae55-5695045b6d68",
"idempotencyKey": "711158de-aaae-4386-80eb-f450cb71e47s",
"actionCode": "711158de-aaae-4386-80eb-f450cb71e47d"
}
}