Skip to main content

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.

caution

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:​

  1. Create a POST endpoint on your server that listens for incoming webhook requests.

  2. Add this endpoint's URL to your authenticator's webhook configuration settings in Authsignal's admin portal.

Verification steps:​

  1. In your webhook function, retrieve the x-signature, content-type and x-timestamp headers from the incoming request.

  2. 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 and x-timestamp request headers. These must be converted to title case as shown.
  • The request body.

  1. Compute the HMAC-SHA256 signature of the message using your secret key in Authsignal's admin portal.

  2. 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.

  3. 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.

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​

Email magic link webhook
type: email.created

  {
    "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"
    }
  }
Email OTP webhook
type: email.created

  {
    "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"
    }
  }
Push webhook
type: push.created

  {
    "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"
    }
  }
SMS webhook
type: sms.created

  {
    "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"
    }
  }