Two-Factor Authentication Webhooks

Two-Factor Authentication (2FA) Webhooks (also known as Callbacks) rely on Delivery Receipts (DLRs) sent to the Two-Factor Authentication platform by both Bandwidth's North America and International messaging platforms. Since these two platforms send different DLR formats, the 2FA platform standardizes them into a singular format for simplicity and ease of consumption. The 2FA platform then takes these DLRs and sends them via an HTTP POST to the URL that was set in the callbackUrl field in the initial request. The callbackUrl field can be any publicly addressable url.

Message Webhooks Concepts

• Both North America and International webhooks have the same fields and have the same format. However, some of these fields have different values between the two systems. More information on format can be found in the following section.
• North America webhooks are retried for 24 hours if the 2FA platform is unable to deliver it to you.
• International webhooks are not retried if the 2FA platform is unable to deliver it to you after the initial delivery attempt.

North America Webhooks

• The 2FA platform considers any message that is sent to a phone number with the country code +1 to be North America.
• The type of North America webhooks are as follows:
  • message-delivered - Message has been delivered to the carrier.
  • message-failed - Message failed to deliver.

International Webhooks

• The 2FA platform considers any message that is sent to a phone number that does not have the country code +1 to be international.
• The type of international webhooks are as follows:
  • message-delivered - Message has been delivered to the carrier.
  • message-failed - Message failed to deliver.

Two-Factor Authentication Provisioning

When Two-Factor Authentication is enabled on your account, the 2FA platform generates a separate Application specifically for 2FA. As part of this application, there is a field present called Callback URL that is auto-populated with a default Callback URL for 2FA. Having this default URL ensures proper routing of requests to the platform, where they can be routed to the URL specified in the callbackUrl field of your initial API request.

See the below image as an example of the Callback URL from the API.

Note: The path parameter yourAccountId is replaced with your overall Bandwidth Account ID during provisioning.

If you change the value in the Bandwidth App in the Callback URL field to something other than the default 2FA Callback URL, you will not get the standardized messages for North America webhooks nor get logging/monitoring support from the 2FA platform. International webhooks will also stop forwarding to your platform but will still log to the 2FA platform.